ccp-protocol 0.4.0__py3-none-any.whl

ccp/model.py

@@ -0,0 +1,187 @@
+"""Protocol data models: Manifest, Grant, Signal, Decision."""
+
+from dataclasses import asdict, dataclass, field
+
+from . import canonical, crypto
+from .errors import AUTHORIZED, CONFIRMATION_REQUIRED, CCPError
+
+
+@dataclass
+class Decision:
+    """The outcome of submitting or confirming a signal."""
+
+    outcome: str
+    request_id: str | None = None
+    pending_id: str | None = None
+    result: object = None
+    error: str | None = None
+    detail: str | None = None
+    state: str | None = None
+
+    @property
+    def authorized(self):
+        return self.outcome == AUTHORIZED
+
+    @property
+    def needs_confirmation(self):
+        return self.outcome == CONFIRMATION_REQUIRED
+
+    @property
+    def rejected(self):
+        return self.outcome not in (AUTHORIZED, CONFIRMATION_REQUIRED)
+
+
+class Manifest:
+    """A signed provider manifest (§8)."""
+
+    def __init__(self, document, data):
+        self.document = document
+        self.data = data
+        self._signing_input = canonical.signing_bytes(document)
+
+    @classmethod
+    def parse(cls, document):
+        data = canonical.parse_strict(document)
+        if not isinstance(data, dict):
+            raise CCPError("invalid_request", "manifest must be a JSON object")
+        for name in ("ccp", "provider", "version", "intents", "signature"):
+            if name not in data:
+                raise CCPError("invalid_request", "manifest missing %r" % (name,))
+        if not isinstance(data["provider"], dict) or "id" not in data["provider"]:
+            raise CCPError("invalid_request", "manifest provider.id is required")
+        if not isinstance(data["intents"], dict):
+            raise CCPError("invalid_request", "manifest intents must be an object")
+        return cls(document, data)
+
+    @property
+    def provider_id(self):
+        return self.data["provider"]["id"]
+
+    @property
+    def provider_name(self):
+        return self.data["provider"].get("name")
+
+    @property
+    def version(self):
+        return self.data["version"]
+
+    @property
+    def intents(self):
+        return self.data["intents"]
+
+    @property
+    def signature(self):
+        return self.data["signature"]
+
+    @property
+    def signing_input(self):
+        return self._signing_input
+
+    @property
+    def digest(self):
+        """`sha256:<hex>` over the canonical signing bytes (§26.1)."""
+        return canonical.digest_bytes(self._signing_input)
+
+    def intent_spec(self, name):
+        return self.intents.get(name)
+
+    def verify(self, expected_provider_id=None):
+        """Verify the manifest signature; raise CCPError on failure."""
+        if expected_provider_id is not None and self.provider_id != expected_provider_id:
+            raise CCPError("unauthenticated", "provider id does not match")
+        key = crypto.VerifyingKey.from_key_id(self.provider_id)
+        if not key.verify(self._signing_input, self.signature):
+            raise CCPError("unauthenticated", "manifest signature is invalid")
+        return True
+
+
+@dataclass
+class Grant:
+    """The consumer's local authorization record (§26.1)."""
+
+    id: str
+    requester_key: str
+    contact_id: str
+    manifest_digest: str
+    manifest_version: int
+    intents: list = field(default_factory=list)
+    limits: dict = field(default_factory=dict)
+    created_at: str = ""
+    expires_at: str = ""
+    confirmation: dict = field(default_factory=dict)
+    capabilities: list = field(default_factory=list)
+    placement: list = field(default_factory=list)
+    egress: dict = field(default_factory=dict)
+    state: str = "active"
+    state_reason: str | None = None
+
+    def is_active(self, now):
+        return self.state == "active" and now < self.expires_at
+
+    def pause(self, reason=None):
+        if self.state in ("revoked", "expired"):
+            raise CCPError("invalid_request", "cannot pause a %s grant" % self.state)
+        self.state = "paused"
+        self.state_reason = reason
+
+    def suspend(self, reason=None):
+        if self.state in ("revoked", "expired"):
+            raise CCPError("invalid_request", "cannot suspend a %s grant" % self.state)
+        self.state = "suspended"
+        self.state_reason = reason
+
+    def resume(self):
+        if self.state not in ("paused", "suspended"):
+            raise CCPError("invalid_request", "cannot resume a %s grant" % self.state)
+        self.state = "active"
+        self.state_reason = None
+
+    def revoke(self, reason=None):
+        self.state = "revoked"
+        self.state_reason = reason
+
+    def to_dict(self):
+        return asdict(self)
+
+    @classmethod
+    def from_dict(cls, data):
+        return cls(**data)
+
+
+class Signal:
+    """A signed request to invoke one intent (§10.1)."""
+
+    FIELDS = ("ccp", "request_id", "grant_digest", "intent", "params",
+              "issued_at", "expires_at", "signature")
+
+    def __init__(self, document, data):
+        self.document = document
+        self.data = data
+        self._signing_input = canonical.signing_bytes(document)
+
+    @classmethod
+    def parse(cls, document):
+        data = canonical.parse_strict(document)
+        if not isinstance(data, dict):
+            raise CCPError("invalid_request", "signal must be a JSON object")
+        for name in cls.FIELDS:
+            if name not in data:
+                raise CCPError("invalid_request", "signal missing %r" % (name,))
+        return cls(document, data)
+
+    @property
+    def request_id(self):
+        return self.data["request_id"]
+
+    @property
+    def intent(self):
+        return self.data["intent"]
+
+    @property
+    def params(self):
+        return self.data["params"]
+
+    def verify(self, verifying_key):
+        if not verifying_key.verify(self._signing_input, self.data["signature"]):
+            raise CCPError("unauthenticated", "signal signature is invalid")
+        return True

ccp/requester.py

@@ -0,0 +1,66 @@
+"""Requester role: build and sign manifests and signals."""
+
+from .errors import CCPError
+from .signing import sign_document
+
+DEFAULT_CCP = "0.4-draft"
+
+
+def build_manifest(provider, version, intents, *, ccp=DEFAULT_CCP):
+    """Build the unsigned manifest mapping (§8)."""
+    if not isinstance(provider, dict) or not provider.get("id"):
+        raise CCPError("invalid_request", "provider.id is required")
+    return {
+        "ccp": ccp,
+        "provider": dict(provider),
+        "version": version,
+        "intents": intents,
+    }
+
+
+def sign_manifest(provider, version, intents, signing_key, *,
+                  ccp=DEFAULT_CCP):
+    """Return a signed manifest in canonical wire form."""
+    return sign_document(
+        build_manifest(provider, version, intents, ccp=ccp), signing_key)
+
+
+def build_signal(request_id, grant_digest, intent, params, issued_at,
+                 expires_at, *, ccp=DEFAULT_CCP):
+    """Build the unsigned signal mapping (§10.1)."""
+    return {
+        "ccp": ccp,
+        "request_id": request_id,
+        "grant_digest": grant_digest,
+        "intent": intent,
+        "params": params,
+        "issued_at": issued_at,
+        "expires_at": expires_at,
+    }
+
+
+def sign_signal(request_id, grant_digest, intent, params, issued_at,
+                expires_at, signing_key, *, ccp=DEFAULT_CCP):
+    """Return a signed signal in canonical wire form."""
+    return sign_document(
+        build_signal(request_id, grant_digest, intent, params, issued_at,
+                     expires_at, ccp=ccp),
+        signing_key,
+    )
+
+
+class Requester:
+    """A signing identity that produces manifests and signals."""
+
+    def __init__(self, signing_key):
+        self.signing_key = signing_key
+        self.key_id = signing_key.key_id
+
+    def manifest(self, provider, version, intents, *, ccp=DEFAULT_CCP):
+        return sign_manifest(provider, version, intents, self.signing_key,
+                             ccp=ccp)
+
+    def signal(self, request_id, grant_digest, intent, params, issued_at,
+               expires_at, *, ccp=DEFAULT_CCP):
+        return sign_signal(request_id, grant_digest, intent, params,
+                           issued_at, expires_at, self.signing_key, ccp=ccp)

ccp/runtime.py

@@ -0,0 +1,200 @@
+"""Reference CCP runtime: validation, confirmation, execution, audit.
+
+Implements the §10.3 validation sequence and the §26.3 side-effect state
+machine. Confirmation is two-phase: :meth:`Runtime.submit` returns
+``confirmation_required`` with a ``pending_id``, and the trusted client
+later calls :meth:`Runtime.confirm`.
+"""
+
+import uuid
+
+from . import canonical, crypto, schema
+from .audit import AuditLog, utcnow
+from .decision import decide
+from .errors import AUTHORIZED, CONFIRMATION_REQUIRED, CCPError
+from .hosts import HostRegistry
+from .model import Decision, Signal
+from .stores import (
+    GrantStore,
+    LimitTracker,
+    ManifestStore,
+    Pending,
+    PendingStore,
+    ReplayStore,
+    SchemaRegistry,
+)
+
+
+class Runtime:
+    def __init__(self, *, grants=None, manifests=None, replay=None, limits=None,
+                 pending=None, schemas=None, hosts=None, audit=None, clock=None,
+                 supported_ccp="0.4-draft"):
+        self.grants = grants if grants is not None else GrantStore()
+        self.manifests = manifests if manifests is not None else ManifestStore()
+        self.schemas = schemas if schemas is not None else SchemaRegistry()
+        self.hosts = hosts if hosts is not None else HostRegistry()
+        self.audit = audit if audit is not None else AuditLog()
+        self.replay = replay if replay is not None else ReplayStore()
+        self.limits = limits if limits is not None else LimitTracker()
+        self.pending_store = pending if pending is not None else PendingStore()
+        self.clock = clock or utcnow
+        self.supported_ccp = supported_ccp
+
+    # -- public API ------------------------------------------------------
+
+    def submit(self, document, verifying_key=None):
+        """Validate and act on one signed signal."""
+        now = self.clock()
+        try:
+            signal = Signal.parse(document)
+        except (canonical.CanonicalError, CCPError) as exc:
+            return self._reject("invalid_request", None, detail=str(exc))
+        request_id = signal.request_id
+
+        # authenticate the sender (transport provides the bound key)
+        if verifying_key is None:
+            return self._reject("unauthenticated", request_id,
+                                detail="no authenticated signer")
+        try:
+            if not verifying_key.verify(signal._signing_input,
+                                        signal.data["signature"]):
+                return self._reject("unauthenticated", request_id,
+                                    detail="signature mismatch")
+        except (crypto.CryptoError, KeyError) as exc:
+            return self._reject("unauthenticated", request_id, detail=str(exc))
+
+        signer = verifying_key.key_id
+
+        # resolve the grant and its approved manifest
+        grant = self.grants.find(signer, signal.data["grant_digest"])
+        intent_spec = None
+        params_schema = None
+        if grant is not None:
+            manifest = self.manifests.get(grant.manifest_digest)
+            if manifest is not None:
+                intent_spec = manifest.intent_spec(signal.data["intent"])
+                if intent_spec is not None:
+                    params_schema = self.schemas.get(
+                        intent_spec.get("params_schema"))
+        counters = self.limits.counters(grant.id) if grant is not None else {}
+
+        decision = decide(
+            grant, signal.data, signer, now,
+            self.replay.snapshot(), counters,
+            intent_spec=intent_spec, params_schema=params_schema,
+            supported_ccp=self.supported_ccp,
+        )
+        if decision not in (AUTHORIZED, CONFIRMATION_REQUIRED):
+            return self._reject(decision, request_id, grant)
+
+        # accepted: apply replay and limit guards atomically
+        if not self.replay.mark_if_new(request_id):
+            return self._reject("replay_detected", request_id, grant)
+        if not self.limits.try_reserve(grant.id, grant.limits):
+            return self._reject("limit_exceeded", request_id, grant)
+
+        required = intent_spec.get("required_capabilities", [])
+        unavailable = [c for c in required if not self.hosts.has_host(c)]
+        if unavailable or not self.hosts.has_intent(signal.data["intent"]):
+            self.limits.release(grant.id, grant.limits)
+            return self._reject("capability_unavailable", request_id, grant,
+                                detail="unavailable: %s"
+                                % (unavailable or signal.data["intent"]))
+
+        if decision == CONFIRMATION_REQUIRED:
+            pending_id = uuid.uuid4().hex
+            self.pending_store.put(
+                Pending(pending_id, signal, grant, intent_spec))
+            self._audit("awaiting_confirmation", signal, grant)
+            return Decision(CONFIRMATION_REQUIRED, request_id=request_id,
+                            pending_id=pending_id,
+                            state="awaiting_confirmation")
+
+        return self._execute(signal, grant, intent_spec)
+
+    def confirm(self, pending_id, approved):
+        """Resolve a pending confirmation."""
+        pending = self.pending_store.take(pending_id)
+        if pending is None:
+            return self._reject("invalid_request", None,
+                                detail="unknown pending request")
+
+        if not approved:
+            self.limits.release(pending.grant.id, pending.grant.limits)
+            self._audit("cancelled", pending.signal, pending.grant)
+            return Decision("cancelled", request_id=pending.signal.request_id,
+                            state="cancelled")
+
+        # The grant may have changed while the prompt was open (§9.4.3).
+        state_error = self._grant_state_error(pending.grant, self.clock())
+        if state_error:
+            self.limits.release(pending.grant.id, pending.grant.limits)
+            return self._reject(state_error, pending.signal.request_id,
+                                pending.grant)
+
+        return self._execute(pending.signal, pending.grant, pending.intent_spec)
+
+    def pending(self, pending_id):
+        return self.pending_store.get(pending_id)
+
+    # -- internals -------------------------------------------------------
+
+    def _execute(self, signal, grant, intent_spec):
+        self._audit("executing", signal, grant)
+        executor = self.hosts.intent(signal.data["intent"])
+        access = self.hosts.access(grant.capabilities)
+        try:
+            result = executor(signal.data["params"], access)
+        except Exception as exc:  # noqa: BLE001 - surfaced as a typed outcome
+            self.limits.release(grant.id, grant.limits)
+            self._audit("failed", signal, grant, detail=str(exc))
+            return Decision("execution_failed", request_id=signal.request_id,
+                            error="execution_failed", detail=str(exc),
+                            state="failed")
+
+        result_schema = self.schemas.get(intent_spec.get("result_schema"))
+        if result_schema is not None:
+            problems = schema.validate(result, result_schema)
+            if problems:
+                self.limits.release(grant.id, grant.limits)
+                self._audit("failed", signal, grant, detail="invalid result")
+                return Decision("execution_failed", request_id=signal.request_id,
+                                error="execution_failed",
+                                detail="invalid result: " + "; ".join(problems),
+                                state="failed")
+
+        self.limits.commit(grant.id, grant.limits)
+        self._audit("completed", signal, grant)
+        return Decision(AUTHORIZED, request_id=signal.request_id,
+                        result=result, state="completed")
+
+    @staticmethod
+    def _grant_state_error(grant, now):
+        if grant.state == "revoked":
+            return "grant_revoked"
+        if grant.state == "paused":
+            return "grant_paused"
+        if grant.state == "suspended":
+            return "grant_suspended"
+        if grant.state == "expired" or now >= grant.expires_at:
+            return "grant_expired"
+        return None
+
+    def _reject(self, code, request_id, grant=None, detail=None):
+        self._audit("rejected", None, grant, request_id=request_id,
+                    code=code, detail=detail)
+        return Decision(code, request_id=request_id, error=code, detail=detail)
+
+    def _audit(self, event, signal=None, grant=None, request_id=None,
+               code=None, detail=None):
+        record = {"event": event, "grant_id": grant.id if grant else None}
+        if signal is not None:
+            record["request_id"] = signal.request_id
+            record["intent"] = signal.data.get("intent")
+        if request_id is not None:
+            record["request_id"] = request_id
+        if code is not None:
+            record["code"] = code
+        if detail is not None:
+            record["detail"] = detail
+        self.audit.append(record)

ccp/schema.py

@@ -0,0 +1,134 @@
+"""A minimal JSON Schema subset validator per CCP §25.3.
+
+Supports the frozen subset used by the profile: ``type``, ``properties``,
+``required``, ``additionalProperties``, ``items``, ``enum``, ``const``,
+numeric bounds and ``multipleOf``, string length, array length and
+uniqueness, and ``pattern``. Unknown keywords are ignored.
+
+This is a reference validator, not a full JSON Schema implementation.
+"""
+
+import re
+
+
+class SchemaError(ValueError):
+    pass
+
+
+def validate(value, schema):
+    """Return a list of human-readable violations (empty means valid)."""
+    errors = []
+    _validate(value, schema, "$", errors)
+    return errors
+
+
+def is_valid(value, schema):
+    return not validate(value, schema)
+
+
+def _type_ok(value, name):
+    if name == "object":
+        return isinstance(value, dict)
+    if name == "array":
+        return isinstance(value, list)
+    if name == "string":
+        return isinstance(value, str)
+    if name == "integer":
+        return isinstance(value, int) and not isinstance(value, bool)
+    if name == "number":
+        return isinstance(value, (int, float)) and not isinstance(value, bool)
+    if name == "boolean":
+        return isinstance(value, bool)
+    if name == "null":
+        return value is None
+    raise SchemaError("unsupported type: %r" % (name,))
+
+
+def _validate(value, schema, path, errors):
+    if schema is False:
+        errors.append("%s: not allowed" % path)
+        return
+    if schema is True or schema is None:
+        return
+
+    expected = schema.get("type")
+    if expected is not None:
+        names = expected if isinstance(expected, list) else [expected]
+        if not any(_type_ok(value, n) for n in names):
+            errors.append("%s: expected %s" % (path, "/".join(names)))
+            return
+
+    if "const" in schema and value != schema["const"]:
+        errors.append("%s: must equal %r" % (path, schema["const"]))
+    if "enum" in schema and value not in schema["enum"]:
+        errors.append("%s: must be one of %r" % (path, schema["enum"]))
+
+    if isinstance(value, bool):
+        return
+
+    if isinstance(value, (int, float)):
+        _validate_number(value, schema, path, errors)
+    if isinstance(value, str):
+        _validate_string(value, schema, path, errors)
+    if isinstance(value, list):
+        _validate_array(value, schema, path, errors)
+    if isinstance(value, dict):
+        _validate_object(value, schema, path, errors)
+
+
+def _validate_number(value, schema, path, errors):
+    if "minimum" in schema and value < schema["minimum"]:
+        errors.append("%s: below minimum" % path)
+    if "maximum" in schema and value > schema["maximum"]:
+        errors.append("%s: above maximum" % path)
+    if "exclusiveMinimum" in schema and value <= schema["exclusiveMinimum"]:
+        errors.append("%s: not above exclusiveMinimum" % path)
+    if "exclusiveMaximum" in schema and value >= schema["exclusiveMaximum"]:
+        errors.append("%s: not below exclusiveMaximum" % path)
+    if "multipleOf" in schema:
+        step = schema["multipleOf"]
+        if step:
+            if (isinstance(value, int) and not isinstance(value, bool)
+                    and isinstance(step, int)):
+                if value % step != 0:
+                    errors.append("%s: not a multiple of %r" % (path, step))
+            elif abs(value / step - round(value / step)) > 1e-9:
+                errors.append("%s: not a multiple of %r" % (path, step))
+
+
+def _validate_string(value, schema, path, errors):
+    if "minLength" in schema and len(value) < schema["minLength"]:
+        errors.append("%s: shorter than minLength" % path)
+    if "maxLength" in schema and len(value) > schema["maxLength"]:
+        errors.append("%s: longer than maxLength" % path)
+    if "pattern" in schema and re.search(schema["pattern"], value) is None:
+        errors.append("%s: does not match pattern" % path)
+
+
+def _validate_array(value, schema, path, errors):
+    if "minItems" in schema and len(value) < schema["minItems"]:
+        errors.append("%s: fewer than minItems" % path)
+    if "maxItems" in schema and len(value) > schema["maxItems"]:
+        errors.append("%s: more than maxItems" % path)
+    if schema.get("uniqueItems"):
+        if len({repr(v) for v in value}) != len(value):
+            errors.append("%s: items are not unique" % path)
+    items = schema.get("items")
+    if items is not None:
+        for index, item in enumerate(value):
+            _validate(item, items, "%s[%d]" % (path, index), errors)
+
+
+def _validate_object(value, schema, path, errors):
+    properties = schema.get("properties", {})
+    for name in schema.get("required", []):
+        if name not in value:
+            errors.append("%s.%s: required" % (path, name))
+    additional = schema.get("additionalProperties", True)
+    for name, item in value.items():
+        if name in properties:
+            _validate(item, properties[name], "%s.%s" % (path, name), errors)
+        elif additional is False:
+            errors.append("%s.%s: additional property not allowed" % (path, name))
+        elif isinstance(additional, dict):
+            _validate(item, additional, "%s.%s" % (path, name), errors)

ccp/signing.py

@@ -0,0 +1,14 @@
+"""Helpers for signing CCP documents."""
+
+from . import canonical
+
+
+def sign_document(value, signing_key):
+    """Return the canonical wire form of ``value`` signed by ``signing_key``.
+
+    The value is a mapping; any existing ``signature`` key is replaced.
+    """
+    value = dict(value)
+    value.pop("signature", None)
+    value["signature"] = signing_key.sign(canonical.signing_bytes_of(value))
+    return canonical.serialize(value)

ccp/state_machine.py

@@ -0,0 +1,33 @@
+"""The side-effect state machine (§26.3)."""
+
+#: (from, event) -> to. ``None`` is the start pseudo-state.
+TRANSITIONS = {
+    (None, "arrive"): "received",
+    ("received", "validate_ok"): "authorized",
+    ("authorized", "confirmation_required"): "awaiting_confirmation",
+    ("authorized", "no_confirmation"): "executing",
+    ("awaiting_confirmation", "approved"): "executing",
+    ("awaiting_confirmation", "denied"): "cancelled",
+    ("executing", "succeeded"): "completed",
+    ("executing", "failed"): "failed",
+    ("executing", "cancelled"): "cancelled",
+    ("executing", "outcome_lost"): "outcome_unknown",
+}
+
+TERMINAL = frozenset({"completed", "failed", "cancelled", "outcome_unknown"})
+
+
+def next_state(state, event):
+    """Return the state after ``event``; raise ValueError if undefined."""
+    if state == "start":
+        state = None
+    try:
+        return TRANSITIONS[(state, event)]
+    except KeyError:
+        raise ValueError("no transition from %r on %r" % (state, event))
+
+
+def reachable_states():
+    states = set(TRANSITIONS.values())
+    states.update(state for (state, _event) in TRANSITIONS if state is not None)
+    return states