ccp-protocol 0.4.0__py3-none-any.whl

ccp/canonical.py

@@ -0,0 +1,192 @@
+"""Strict canonical JSON per CCP §25.1.
+
+The canonical form is deterministic and byte-exact:
+
+* numbers: only non-negative integers; floats, exponents, negatives, NaN,
+  Infinity and -Infinity are rejected;
+* strings: UTF-8, NFC-normalized (keys and values), minimal escaping;
+* objects: keys other than ``signature`` sorted by Unicode code point;
+  duplicate keys rejected; ``signature`` always emitted last;
+* arrays: order preserved; no insignificant whitespace;
+* any JSON value is supported, including top-level scalars.
+"""
+
+import hashlib
+import json
+import unicodedata
+
+
+class CanonicalError(ValueError):
+    """Raised when a value cannot be represented in canonical form."""
+
+    def __init__(self, code):
+        self.code = code
+        super().__init__(code)
+
+
+_SHORT_ESCAPES = {
+    "\b": "\\b",
+    "\f": "\\f",
+    "\n": "\\n",
+    "\r": "\\r",
+    "\t": "\\t",
+}
+
+
+def _require_well_formed(text):
+    """Reject strings containing unpaired surrogates (§25.1 UTF-8)."""
+    for char in text:
+        if 0xD800 <= ord(char) <= 0xDFFF:
+            raise CanonicalError("malformed")
+
+
+def quote(s):
+    """Encode one string using the minimal escape set."""
+    _require_well_formed(s)
+    s = unicodedata.normalize("NFC", s)
+    out = ['"']
+    for ch in s:
+        if ch == '"':
+            out.append('\\"')
+        elif ch == "\\":
+            out.append("\\\\")
+        elif ch in _SHORT_ESCAPES:
+            out.append(_SHORT_ESCAPES[ch])
+        elif ord(ch) < 0x20:
+            out.append("\\u%04x" % ord(ch))
+        else:
+            out.append(ch)
+    out.append('"')
+    return "".join(out)
+
+
+def serialize(value, _top=True):
+    """Serialize a parsed JSON value in canonical form."""
+    if value is None:
+        return "null"
+    if value is True:
+        return "true"
+    if value is False:
+        return "false"
+    if isinstance(value, str):
+        return quote(value)
+    if isinstance(value, int):
+        if value < 0:
+            raise CanonicalError("negative")
+        return str(value)
+    if isinstance(value, float):
+        raise CanonicalError("float")
+    if isinstance(value, list):
+        return "[" + ",".join(serialize(v, _top=False) for v in value) + "]"
+    if isinstance(value, dict):
+        if _top and "signature" in value:
+            regular = {k: v for k, v in value.items() if k != "signature"}
+        else:
+            regular = value
+        folded = {}
+        for key, item in regular.items():
+            nfc = unicodedata.normalize("NFC", key)
+            if nfc in folded:
+                raise CanonicalError("duplicate")
+            folded[nfc] = item
+        parts = [quote(k) + ":" + serialize(folded[k], _top=False)
+                 for k in sorted(folded)]
+        if _top and "signature" in value:
+            parts.append(quote("signature") + ":"
+                         + serialize(value["signature"], _top=False))
+        return "{" + ",".join(parts) + "}"
+    raise TypeError("unsupported type %r" % (type(value),))
+
+
+def _reject_dupes(pairs):
+    seen = {}
+    for key, value in pairs:
+        if key in seen:
+            raise CanonicalError("duplicate")
+        seen[key] = value
+    return seen
+
+
+def _reject_constant(_name):
+    raise CanonicalError("constant")
+
+
+def _parse_int(text):
+    if text.startswith("-"):
+        raise CanonicalError("negative")
+    return int(text)
+
+
+def _parse_float(text):
+    if text.startswith("-"):
+        raise CanonicalError("negative")
+    raise CanonicalError("float")
+
+
+def _check(value):
+    """Validate decoded strings and NFC key uniqueness."""
+    if isinstance(value, str):
+        _require_well_formed(value)
+    elif isinstance(value, list):
+        for item in value:
+            _check(item)
+    elif isinstance(value, dict):
+        seen = set()
+        for key, item in value.items():
+            _require_well_formed(key)
+            folded = unicodedata.normalize("NFC", key)
+            if folded in seen:
+                raise CanonicalError("duplicate")
+            seen.add(folded)
+            _check(item)
+
+
+def parse_strict(document):
+    """Parse a JSON document with duplicate-key and NaN/Infinity rejection."""
+    try:
+        value = json.loads(
+            document,
+            object_pairs_hook=_reject_dupes,
+            parse_constant=_reject_constant,
+            parse_int=_parse_int,
+            parse_float=_parse_float,
+        )
+    except json.JSONDecodeError as exc:
+        raise CanonicalError("malformed") from exc
+    _check(value)
+    return value
+
+
+def canonicalize(document):
+    """Canonicalize a JSON document string."""
+    return serialize(parse_strict(document))
+
+
+def signing_bytes(document):
+    """Canonical bytes signed for a document; ``signature`` excluded."""
+    obj = parse_strict(document)
+    obj.pop("signature", None)
+    return serialize(obj).encode("utf-8")
+
+
+def signing_bytes_of(value):
+    """Canonical bytes signed for an already-parsed value."""
+    obj = dict(value)
+    obj.pop("signature", None)
+    return serialize(obj).encode("utf-8")
+
+
+def signed_wire(document, signature_b64url):
+    """Wire form: canonical document with ``signature`` appended last."""
+    obj = parse_strict(document)
+    obj["signature"] = "ed25519:" + signature_b64url
+    return serialize(obj)
+
+
+def digest_bytes(data):
+    return "sha256:" + hashlib.sha256(data).hexdigest()
+
+
+def digest_of(document):
+    """`sha256:<hex>` over the canonical signing bytes of a document."""
+    return digest_bytes(signing_bytes(document))

ccp/consumer.py

@@ -0,0 +1,75 @@
+"""Consumer role: verify inbound documents and build permission cards."""
+
+from dataclasses import asdict, dataclass
+
+from .errors import CCPError
+from .model import Manifest, Signal
+
+
+def verify_manifest(document, expected_provider_id=None):
+    """Parse and verify a signed manifest (§8), returning the `Manifest`."""
+    manifest = Manifest.parse(document)
+    manifest.verify(expected_provider_id)
+    return manifest
+
+
+def verify_signal(document, verifying_key):
+    """Parse and verify a signed signal (§10.1), returning the `Signal`."""
+    signal = Signal.parse(document)
+    signal.verify(verifying_key)
+    return signal
+
+
+@dataclass
+class PermissionCard:
+    """Plain-language permission card for a trusted UI (§11.4)."""
+
+    who: str
+    what: str
+    data_read: list
+    where: str
+    egress: str
+    effects: str
+    recurrence: str
+    revoke: str
+
+    def to_dict(self):
+        return asdict(self)
+
+
+def permission_card(manifest, intent, *, provider_name=None, data_read=None,
+                    where=None, effects=None, recurrence="once", revoke=None):
+    """Build the §11.4 card for one intent of a verified manifest."""
+    definition = (manifest.intents or {}).get(intent)
+    if definition is None:
+        raise CCPError("intent_not_allowed", "unknown intent %r" % (intent,))
+
+    who = provider_name or manifest.provider_name or manifest.provider_id
+    placement = definition.get("placement", "local")
+    egress_spec = definition.get("data_egress") or {}
+    network = egress_spec.get("network") is True
+    fields = egress_spec.get("fields") or []
+
+    if where is None:
+        where = ("on this device" if placement == "local"
+                 else "via %s" % placement)
+    if network:
+        egress = "sends %s to a remote endpoint" % (
+            ", ".join(fields) or "declared fields")
+    else:
+        egress = "does not send data off the device"
+
+    return PermissionCard(
+        who=who,
+        what=definition.get("description", intent),
+        data_read=list(
+            data_read if data_read is not None
+            else definition.get("required_capabilities") or []
+        ),
+        where=where,
+        egress=egress,
+        effects=effects or "no external side effect declared",
+        recurrence=("applies to future requests" if recurrence == "future"
+                    else "applies once"),
+        revoke=revoke or "you can revoke this grant at any time",
+    )

ccp/crypto.py

@@ -0,0 +1,96 @@
+"""Ed25519 key and signature encoding per CCP §25.2."""
+
+import base64
+
+from cryptography.exceptions import InvalidSignature
+from cryptography.hazmat.primitives import serialization
+from cryptography.hazmat.primitives.asymmetric.ed25519 import (
+    Ed25519PrivateKey,
+    Ed25519PublicKey,
+)
+
+KEY_PREFIX = "key:ed25519:"
+SIG_PREFIX = "ed25519:"
+
+
+class CryptoError(ValueError):
+    pass
+
+
+def b64url_encode(raw):
+    return base64.urlsafe_b64encode(raw).rstrip(b"=").decode("ascii")
+
+
+def b64url_decode(text):
+    pad = "=" * (-len(text) % 4)
+    return base64.urlsafe_b64decode(text + pad)
+
+
+def key_id_from_public_bytes(raw):
+    return KEY_PREFIX + b64url_encode(raw)
+
+
+def public_bytes_from_key_id(key_id):
+    if not key_id.startswith(KEY_PREFIX):
+        raise CryptoError("unsupported key identifier: %r" % (key_id,))
+    return b64url_decode(key_id[len(KEY_PREFIX):])
+
+
+class SigningKey:
+    """A 32-byte RFC 8032 seed and its Ed25519 signer."""
+
+    def __init__(self, private_key):
+        self._key = private_key
+
+    @classmethod
+    def generate(cls):
+        return cls(Ed25519PrivateKey.generate())
+
+    @classmethod
+    def from_seed(cls, seed):
+        if len(seed) != 32:
+            raise CryptoError("seed must be 32 bytes")
+        return cls(Ed25519PrivateKey.from_private_bytes(seed))
+
+    @property
+    def public_bytes(self):
+        return self._key.public_key().public_bytes(
+            serialization.Encoding.Raw, serialization.PublicFormat.Raw)
+
+    @property
+    def key_id(self):
+        return key_id_from_public_bytes(self.public_bytes)
+
+    def verifying_key(self):
+        return VerifyingKey(self._key.public_key())
+
+    def sign(self, message):
+        """Return the signature field value `ed25519:<base64url>`."""
+        return SIG_PREFIX + b64url_encode(self._key.sign(message))
+
+
+class VerifyingKey:
+    def __init__(self, public_key):
+        self._key = public_key
+
+    @classmethod
+    def from_key_id(cls, key_id):
+        raw = public_bytes_from_key_id(key_id)
+        return cls(Ed25519PublicKey.from_public_bytes(raw))
+
+    @property
+    def key_id(self):
+        return key_id_from_public_bytes(
+            self._key.public_bytes(
+                serialization.Encoding.Raw, serialization.PublicFormat.Raw))
+
+    def verify(self, message, signature_field):
+        """Verify an `ed25519:<base64url>` signature over ``message``."""
+        if not isinstance(signature_field, str) or not signature_field.startswith(SIG_PREFIX):
+            raise CryptoError("unsupported signature encoding")
+        raw = b64url_decode(signature_field[len(SIG_PREFIX):])
+        try:
+            self._key.verify(raw, message)
+            return True
+        except InvalidSignature:
+            return False

ccp/decision.py

@@ -0,0 +1,81 @@
+"""The pure §10.3 validation decision.
+
+Separated from the runtime so it can be tested directly against the frozen
+validation vectors without performing side effects. The runtime calls this
+and then applies the side effects (replay marking, limit reservation,
+confirmation, execution) atomically.
+"""
+
+from . import schema
+
+
+def decide(grant, signal, signer, now, seen, counters, *,
+           intent_spec=None, params_schema=None, supported_ccp="0.4-draft"):
+    """Return the §10.3 decision: ``authorized``,
+    ``confirmation_required``, or a rejection code."""
+    # 3. protocol compatibility
+    if signal.get("ccp") != supported_ccp:
+        return "invalid_request"
+
+    # 4. locate the grant
+    if grant is None:
+        return "no_matching_grant"
+
+    # 2. authenticate the sender against the grant's requester
+    if signer != grant.requester_key:
+        return "unauthenticated"
+    if signal.get("grant_digest") != grant.manifest_digest:
+        return "no_matching_grant"
+
+    # 5. grant state and expiry (explicit lifecycle states first)
+    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"
+
+    # 6. intent enabled
+    intent = signal.get("intent")
+    if intent not in grant.intents:
+        return "intent_not_allowed"
+
+    # 7. parameters against the approved schema
+    if intent_spec is None or params_schema is None:
+        return "capability_unavailable"
+    if not schema.is_valid(signal.get("params"), params_schema):
+        return "invalid_request"
+
+    # 8. request expiry and replay
+    if now >= signal.get("expires_at", ""):
+        return "request_expired"
+    if signal.get("request_id") in seen:
+        return "replay_detected"
+
+    # 9. cumulative limits
+    for name, maximum in (grant.limits or {}).items():
+        if counters.get(name, 0) + 1 > maximum:
+            return "limit_exceeded"
+
+    # 10. required host capabilities
+    required = intent_spec.get("required_capabilities", [])
+    if not set(required).issubset(set(grant.capabilities or [])):
+        return "capability_unavailable"
+
+    # 11. confirmation policy
+    if confirmation_policy(grant, intent_spec, intent) == "per_action":
+        return "confirmation_required"
+
+    return "authorized"
+
+
+def confirmation_policy(grant, intent_spec, intent_name):
+    policy = (grant.confirmation or {}).get(intent_name)
+    if policy in ("none", "per_action"):
+        return policy
+    policy = intent_spec.get("confirmation")
+    if policy in ("none", "per_action"):
+        return policy
+    return "per_action"

ccp/errors.py

@@ -0,0 +1,35 @@
+"""Typed error codes and exceptions for CCP (§10.4)."""
+
+AUTHORIZED = "authorized"
+CONFIRMATION_REQUIRED = "confirmation_required"
+
+#: Rejection codes from §10.4. ``confirmation_required`` is a transient
+#: success, not a rejection, and is handled separately.
+ERROR_CODES = frozenset({
+    "invalid_request",
+    "unauthenticated",
+    "no_matching_grant",
+    "intent_not_allowed",
+    "grant_expired",
+    "grant_revoked",
+    "grant_paused",
+    "grant_suspended",
+    "limit_exceeded",
+    "request_expired",
+    "replay_detected",
+    "capability_unavailable",
+    "execution_failed",
+    "outcome_unknown",
+})
+
+
+class CCPError(Exception):
+    """An error carrying one of the §10.4 codes."""
+
+    def __init__(self, code, message=""):
+        if code not in ERROR_CODES:
+            raise ValueError("unknown CCP error code: %r" % (code,))
+        self.code = code
+        self.message = message
+        detail = "%s: %s" % (code, message) if message else code
+        super().__init__(detail)

ccp/hosts.py

@@ -0,0 +1,52 @@
+"""Host-function registry and per-request privilege mediation (§26.4).
+
+The runtime passes an :class:`HostAccess` proxy to an intent executor. The
+proxy exposes only the host functions granted to the requester, so an
+executor cannot reach capabilities outside the grant.
+"""
+
+
+class HostAccess:
+    def __init__(self, registry, granted):
+        self._registry = registry
+        self._granted = set(granted)
+
+    def call(self, name, *args, **kwargs):
+        if name not in self._granted:
+            raise PermissionError("host function not granted: %s" % (name,))
+        function = self._registry.host(name)
+        if function is None:
+            raise PermissionError("host function not installed: %s" % (name,))
+        return function(*args, **kwargs)
+
+    def has(self, name):
+        return name in self._granted and self._registry.host(name) is not None
+
+
+class HostRegistry:
+    """Installed intents and their underlying host functions."""
+
+    def __init__(self):
+        self._hosts = {}
+        self._intents = {}
+
+    def register_host(self, name, function):
+        self._hosts[name] = function
+
+    def register_intent(self, name, function):
+        self._intents[name] = function
+
+    def host(self, name):
+        return self._hosts.get(name)
+
+    def has_host(self, name):
+        return name in self._hosts
+
+    def intent(self, name):
+        return self._intents.get(name)
+
+    def has_intent(self, name):
+        return name in self._intents
+
+    def access(self, granted):
+        return HostAccess(self, granted)