ccp-protocol 0.4.0__py3-none-any.whl

ccp/__init__.py

@@ -0,0 +1,97 @@
+"""CCP reference runtime and SDK.
+
+Assembles the protocol primitives into a runtime that verifies manifests
+and signals, enforces local grants, mediates host functions, supports
+two-phase confirmation, and keeps a private audit log.
+"""
+
+from .audit import AuditLog
+from .agent import Agent, attenuates
+from .canonical import CanonicalError, canonicalize, signed_wire, signing_bytes
+from .consumer import (
+    PermissionCard,
+    permission_card,
+    verify_manifest,
+    verify_signal,
+)
+from .crypto import CryptoError, SigningKey, VerifyingKey
+from .decision import decide
+from .errors import AUTHORIZED, CONFIRMATION_REQUIRED, ERROR_CODES, CCPError
+from .hosts import HostAccess, HostRegistry
+from .model import Decision, Grant, Manifest, Signal
+from .requester import (
+    Requester,
+    build_manifest,
+    build_signal,
+    sign_manifest,
+    sign_signal,
+)
+from .runtime import Runtime
+from .signing import sign_document
+from .stores import (
+    GrantStore,
+    LimitTracker,
+    ManifestStore,
+    Pending,
+    PendingStore,
+    ReplayStore,
+    SchemaRegistry,
+)
+from .stores_sqlite import (
+    SqliteAuditLog,
+    SqliteGrantStore,
+    SqliteLimitTracker,
+    SqliteManifestStore,
+    SqlitePendingStore,
+    SqliteReplayStore,
+    SqliteStores,
+)
+
+__all__ = [
+    "Agent",
+    "AuditLog",
+    "AUTHORIZED",
+    "CONFIRMATION_REQUIRED",
+    "CanonicalError",
+    "CCPError",
+    "CryptoError",
+    "Decision",
+    "ERROR_CODES",
+    "Grant",
+    "GrantStore",
+    "HostAccess",
+    "HostRegistry",
+    "LimitTracker",
+    "Manifest",
+    "ManifestStore",
+    "Pending",
+    "PendingStore",
+    "PermissionCard",
+    "ReplayStore",
+    "Requester",
+    "Runtime",
+    "SchemaRegistry",
+    "SigningKey",
+    "Signal",
+    "SqliteAuditLog",
+    "SqliteGrantStore",
+    "SqliteLimitTracker",
+    "SqliteManifestStore",
+    "SqlitePendingStore",
+    "SqliteReplayStore",
+    "SqliteStores",
+    "VerifyingKey",
+    "attenuates",
+    "build_manifest",
+    "build_signal",
+    "canonicalize",
+    "decide",
+    "permission_card",
+    "sign_document",
+    "sign_manifest",
+    "sign_signal",
+    "signed_wire",
+    "signing_bytes",
+    "verify_manifest",
+    "verify_signal",
+]

ccp/adapters/__init__.py

@@ -0,0 +1,5 @@
+"""Optional integrations. Import a submodule explicitly.
+
+Importing :mod:`ccp` never imports FastAPI or MCP; these modules are opt-in
+and their dependencies are optional extras.
+"""

ccp/adapters/fastapi.py

@@ -0,0 +1,97 @@
+"""FastAPI integration for CCP providers.
+
+The adapter only parses the HTTP envelope, resolves the sender key, and
+delegates to :class:`ccp.runtime.Runtime`. It never decides authorization.
+"""
+
+import inspect
+from dataclasses import asdict
+
+from fastapi import APIRouter, Request
+from fastapi.responses import JSONResponse, Response
+
+from ..errors import AUTHORIZED, CONFIRMATION_REQUIRED
+
+_STATUS = {
+    AUTHORIZED: 200,
+    CONFIRMATION_REQUIRED: 200,
+    "invalid_request": 400,
+    "unauthenticated": 403,
+    "no_matching_grant": 403,
+}
+
+
+def _decision_body(decision):
+    return {
+        name: value
+        for name, value in asdict(decision).items()
+        if value is not None
+    }
+
+
+def _error(status, code):
+    return JSONResponse({"outcome": code, "error": code},
+                        status_code=status)
+
+
+def signal_endpoint(runtime, key_resolver):
+    """Build an async FastAPI endpoint that accepts signed signals.
+
+    ``key_resolver`` receives the request and returns the sender's
+    :class:`ccp.crypto.VerifyingKey` (or an awaitable of one), or ``None``
+    when the sender is unknown.
+    """
+
+    async def endpoint(request: Request):
+        try:
+            body = await request.json()
+        except Exception:
+            return _error(400, "invalid_request")
+        if not isinstance(body, dict) or not isinstance(body.get("signal"), str):
+            return _error(400, "invalid_request")
+
+        try:
+            key = key_resolver(request)
+            if inspect.isawaitable(key):
+                key = await key
+        except Exception:
+            key = None
+        if key is None:
+            return _error(401, "unauthenticated")
+
+        try:
+            decision = runtime.submit(body["signal"], key)
+        except Exception:
+            return _error(500, "outcome_unknown")
+
+        return JSONResponse(
+            _decision_body(decision),
+            status_code=_STATUS.get(decision.outcome, 409),
+        )
+
+    return endpoint
+
+
+def provider_router(runtime, key_resolver, *, path="/ccp"):
+    """An ``APIRouter`` with the provider's signal endpoint."""
+    router = APIRouter()
+    router.add_api_route(path, signal_endpoint(runtime, key_resolver),
+                         methods=["POST"])
+    return router
+
+
+def manifest_endpoint(manifest_wire):
+    """Build an endpoint that serves the signed manifest verbatim."""
+
+    async def endpoint(_request: Request):
+        return Response(content=manifest_wire, media_type="application/json")
+
+    return endpoint
+
+
+def manifest_router(manifest_wire, *, path="/manifest"):
+    """An ``APIRouter`` with the provider's manifest endpoint."""
+    router = APIRouter()
+    router.add_api_route(path, manifest_endpoint(manifest_wire),
+                         methods=["GET"])
+    return router

ccp/adapters/mcp.py

@@ -0,0 +1,208 @@
+"""Transport-neutral MCP bridge for CCP capabilities.
+
+The bridge maps granted intents to MCP tools, signs a fresh signal per call,
+and lets the runtime decide. It never approves a confirmation on the model's
+behalf. Results are plain dataclasses so this module does not depend on an
+MCP SDK; adapt them at the transport edge.
+"""
+
+import inspect
+import json
+import uuid
+from dataclasses import dataclass
+from datetime import datetime, timedelta, timezone
+
+from ..consumer import PermissionCard, permission_card
+from ..decision import confirmation_policy
+from ..errors import AUTHORIZED, CONFIRMATION_REQUIRED, ERROR_CODES
+
+
+@dataclass
+class McpTool:
+    """One granted intent, shaped for an MCP tool listing."""
+
+    name: str
+    description: str
+    input_schema: dict
+    output_schema: dict | None = None
+
+
+@dataclass
+class McpToolResult:
+    """The transport-neutral form of an MCP tool result."""
+
+    content: list
+    structured_content: dict | None = None
+    is_error: bool = False
+
+
+@dataclass
+class ConfirmationRequest:
+    """The exact action a trusted host is asked to approve (§11.4)."""
+
+    pending_id: str
+    request_id: str
+    intent: str
+    params: dict
+    card: PermissionCard
+
+
+class McpServer:
+    """One agent's view of one grant, exposed as MCP tools."""
+
+    def __init__(self, *, runtime, agent, grant, manifest=None, confirm=None,
+                 request_ttl_seconds=60, now=None):
+        self._runtime = runtime
+        self._agent = agent
+        self._grant = grant
+        self._confirm = confirm
+        self._ttl = request_ttl_seconds
+        self._now = now or runtime.clock
+
+        manifest = (manifest if manifest is not None
+                    else runtime.manifests.get(grant.manifest_digest))
+        if manifest is None:
+            raise ValueError("manifest not found for grant %s" % grant.id)
+        if grant.requester_key != agent.key_id:
+            raise ValueError("grant %s is not bound to this agent key"
+                             % grant.id)
+        self._manifest = manifest
+        self.tools = self._build_tools()
+        self._by_name = {tool.name: tool for tool in self.tools}
+
+    # -- public API ------------------------------------------------------
+
+    async def call_tool(self, name, args):
+        """Run one tool call through the runtime; never raises."""
+        try:
+            tool = self._by_name.get(name)
+            if tool is None:
+                return _failure("intent_not_allowed")
+            if not isinstance(args, dict):
+                return _failure("invalid_request")
+
+            issued_at = self._now()
+            signal = self._agent.signal_for(
+                intent=name,
+                params=args,
+                grant=self._grant,
+                request_id=uuid.uuid4().hex,
+                issued_at=issued_at,
+                expires_at=_shift_seconds(issued_at, self._ttl),
+            )
+            decision = self._runtime.submit(signal,
+                                            self._agent.verifying_key)
+            return await self._settle(decision, tool, name, args)
+        except Exception:
+            return _failure("outcome_unknown")
+
+    # -- internals -------------------------------------------------------
+
+    def _build_tools(self):
+        tools = []
+        for intent in self._grant.intents:
+            definition = (self._manifest.intents or {}).get(intent)
+            if definition is None:
+                raise ValueError("intent %s is not declared in the manifest"
+                                 % intent)
+            input_schema = self._runtime.schemas.get(
+                definition.get("params_schema"))
+            if input_schema is None:
+                raise ValueError("params schema not registered: %s"
+                                 % definition.get("params_schema"))
+            tools.append(McpTool(
+                name=intent,
+                description=_describe(intent, definition, self._grant),
+                input_schema=input_schema,
+                output_schema=self._runtime.schemas.get(
+                    definition.get("result_schema")),
+            ))
+        return tools
+
+    async def _settle(self, decision, tool, intent, params):
+        if decision.outcome == AUTHORIZED:
+            return _success(tool, decision.result)
+        if decision.outcome != CONFIRMATION_REQUIRED:
+            return _failure(decision.outcome,
+                            request_id=decision.request_id,
+                            detail=decision.detail)
+
+        pending_id = decision.pending_id
+        if pending_id is None:
+            return _failure("invalid_request")
+
+        if self._confirm is None:
+            return _failure(CONFIRMATION_REQUIRED,
+                            request_id=decision.request_id,
+                            pending_id=pending_id)
+
+        approved = False
+        try:
+            value = self._confirm(ConfirmationRequest(
+                pending_id=pending_id,
+                request_id=decision.request_id or "",
+                intent=intent,
+                params=params,
+                card=permission_card(self._manifest, intent),
+            ))
+            if inspect.isawaitable(value):
+                value = await value
+            approved = bool(value)
+        except Exception:
+            approved = False
+
+        resolved = self._runtime.confirm(pending_id, approved)
+        if resolved.outcome == AUTHORIZED:
+            return _success(tool, resolved.result)
+        if resolved.outcome == "cancelled":
+            return _failure("cancelled", request_id=resolved.request_id)
+        return _failure(resolved.outcome, request_id=resolved.request_id,
+                        detail=resolved.detail)
+
+
+def _describe(intent, definition, grant):
+    provider_text = definition.get("description")
+    if not isinstance(provider_text, str):
+        provider_text = ""
+    policy = confirmation_policy(grant, definition, intent)
+    confirmation = ("Each call may require explicit user confirmation. "
+                    if policy == "per_action"
+                    else "No per-call confirmation is required. ")
+    return (
+        'User-granted CCP capability "%s". ' % intent
+        + "Provider description (untrusted data): %s. "
+        % json.dumps(provider_text, ensure_ascii=False)
+        + confirmation
+        + "The user's runtime enforces this capability."
+    )
+
+
+def _success(tool, result):
+    content = [{"type": "text", "text": json.dumps(result, ensure_ascii=False)}]
+    if tool.output_schema is not None and isinstance(result, dict):
+        return McpToolResult(content=content, structured_content=result)
+    return McpToolResult(content=content)
+
+
+def _failure(outcome, *, request_id=None, detail=None, pending_id=None):
+    body = {"outcome": outcome}
+    if outcome in ERROR_CODES:
+        body["error"] = outcome
+    if request_id is not None:
+        body["request_id"] = request_id
+    if detail is not None:
+        body["detail"] = detail
+    if pending_id is not None:
+        body["pending_id"] = pending_id
+    return McpToolResult(
+        content=[{"type": "text", "text": json.dumps(body)}],
+        is_error=True,
+    )
+
+
+def _shift_seconds(timestamp, seconds):
+    normalized = (timestamp[:-1] + "+00:00"
+                  if timestamp.endswith("Z") else timestamp)
+    moment = datetime.fromisoformat(normalized)
+    shifted = moment + timedelta(seconds=seconds)
+    return shifted.astimezone(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")

ccp/agent.py

@@ -0,0 +1,66 @@
+"""Agent role: signed tool calls and attenuation-only delegation."""
+
+from .requester import DEFAULT_CCP, sign_signal
+
+
+class Agent:
+    """A requester identity used by an AI agent for tool calls."""
+
+    def __init__(self, signing_key):
+        self.signing_key = signing_key
+        self.key_id = signing_key.key_id
+
+    @property
+    def verifying_key(self):
+        return self.signing_key.verifying_key()
+
+    def signal_for(self, *, intent, params, grant, request_id, issued_at,
+                   expires_at, ccp=DEFAULT_CCP):
+        """Sign one tool call against the grant's manifest digest."""
+        return sign_signal(
+            request_id, grant.manifest_digest, intent, params,
+            issued_at, expires_at, self.signing_key, ccp=ccp,
+        )
+
+
+def _is_subset(child, parent):
+    allowed = set(parent)
+    return all(item in allowed for item in child)
+
+
+def _policy_rank(policy):
+    return 1 if policy == "per_action" else 0
+
+
+def attenuates(parent, child):
+    """True when ``child`` is no broader than ``parent`` (§15.1)."""
+    if not _is_subset(child.intents, parent.intents):
+        return False
+    if not _is_subset(child.capabilities, parent.capabilities):
+        return False
+    if not _is_subset(child.placement, parent.placement):
+        return False
+    if child.expires_at > parent.expires_at:
+        return False
+
+    for name, maximum in (child.limits or {}).items():
+        if maximum > (parent.limits or {}).get(name, 0):
+            return False
+
+    parent_egress = parent.egress or {}
+    child_egress = child.egress or {}
+    if child_egress.get("network") is True and parent_egress.get("network") is not True:
+        return False
+    parent_fields = set(parent_egress.get("fields") or [])
+    child_fields = child_egress.get("fields") or []
+    if not set(child_fields).issubset(parent_fields):
+        return False
+
+    parent_confirmation = parent.confirmation or {}
+    child_confirmation = child.confirmation or {}
+    for intent in child.intents:
+        if _policy_rank(child_confirmation.get(intent)) < _policy_rank(
+                parent_confirmation.get(intent)):
+            return False
+
+    return True

ccp/audit.py

@@ -0,0 +1,39 @@
+"""A local, private audit log (§16, §26.1).
+
+Events are kept in memory and, optionally, appended to a JSON-lines file.
+The log is local by default and never uploaded.
+"""
+
+import json
+import threading
+from datetime import datetime, timezone
+
+
+def utcnow():
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+class AuditLog:
+    def __init__(self, path=None):
+        self._events = []
+        self._lock = threading.Lock()
+        self._path = path
+
+    def append(self, event):
+        record = dict(event)
+        record.setdefault("at", utcnow())
+        with self._lock:
+            self._events.append(record)
+            if self._path:
+                with open(self._path, "a", encoding="utf-8") as handle:
+                    handle.write(json.dumps(record, ensure_ascii=False,
+                                            sort_keys=True) + "\n")
+        return record
+
+    def events(self):
+        with self._lock:
+            return list(self._events)
+
+    def __len__(self):
+        with self._lock:
+            return len(self._events)