webagent-protocol 0.2.0__py3-none-any.whl

wap/spec/conversation.py

@@ -0,0 +1,231 @@
+"""Conversation guards: stop two agents from talking in circles.
+
+When an LLM-driven user agent negotiates with an LLM-driven business agent,
+neither side is guaranteed to converge. Typical failure modes are:
+
+* **stuck repetition**: the same question gets the same answer again and again
+  ("do you have croissants?" → "yes, 24" → "do you have croissants?" …);
+* **ping-pong cycles**: the agents alternate between two or three states
+  (offer A → counter B → offer A → counter B …);
+* **stalls**: the same request over and over while only a counter or timestamp
+  in the answer changes;
+* **runaway sessions**: an unbounded number of turns, each costing tokens.
+
+:class:`ConversationGuard` detects all three from *fingerprints* of each
+exchange (request plus reply). Fingerprints ignore message ids, timestamps,
+signatures, proof-of-work and trivial formatting (case, whitespace,
+punctuation), so cosmetic rephrasing does not hide a loop. A repeated request
+that gets a *different* answer (for example, polling stock that is changing) is
+progress, not a loop.
+
+The same guard runs on both sides:
+
+* the business agent refuses a request that would continue a detected loop,
+  *before* running any tool (``loop_detected`` / ``conversation_limit`` errors);
+* the user agent (``WAPSession``, the MCP bridge) stops itself and tells the
+  model to report back to the user instead of retrying.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import re
+import time
+from collections import deque
+from dataclasses import dataclass, field
+from typing import Any
+
+from .crypto import canonical_json
+
+_PUNCT = re.compile(r"[^\w]+", re.UNICODE)
+
+
+def normalize_text(text: str) -> str:
+    """Case-, whitespace- and punctuation-insensitive form of ``text``."""
+    return " ".join(_PUNCT.sub(" ", text.lower()).split())
+
+
+def fingerprint(*parts: Any) -> str:
+    """Stable short hash of JSON-compatible parts (strings are normalised)."""
+    normalised = [normalize_text(p) if isinstance(p, str) else p for p in parts]
+    return hashlib.sha256(canonical_json(normalised)).hexdigest()[:16]
+
+
+def request_fingerprint(capability_id: str | None, structured_data: dict[str, Any] | None, content: str) -> str:
+    return fingerprint("req", capability_id or "", structured_data or {}, content or "")
+
+
+def reply_fingerprint(content: str, structured_data: dict[str, Any] | None) -> str:
+    return fingerprint("rep", content or "", structured_data or {})
+
+
+class ConversationLimitError(Exception):
+    """Raised when a conversation must stop. ``reason`` is ``"loop_detected"`` or ``"conversation_limit"``."""
+
+    def __init__(self, reason: str, message: str, details: dict[str, Any] | None = None) -> None:
+        super().__init__(message)
+        self.reason = reason
+        self.message = message
+        self.details = details or {}
+
+
+@dataclass(frozen=True)
+class ConversationPolicy:
+    """Loop-protection limits. Published by business agents in ``conversation_policy``."""
+
+    max_turns: int = 100
+    """Hard cap on turns in one session."""
+    max_repeats: int = 3
+    """How many times the same exchange (or cycle of exchanges) may occur in a row."""
+    max_cycle_length: int = 3
+    """Longest cycle (in turns) that is detected, e.g. 2 catches A-B-A-B ping-pong."""
+    window_seconds: float = 300.0
+    """Only exchanges this recent count towards repetition; older ones are forgotten."""
+    max_identical_requests: int = 5
+    """The same request may be sent at most this many times in a row, even if answers differ
+    (catches stalls where only counters or timestamps change). Raise it for deliberate polling."""
+    max_duration_seconds: float | None = None
+    """Optional wall-clock limit for one session, measured from its first turn."""
+    max_repeats_across_sessions: int = 10
+    """Looser threshold for loops that hop across fresh session ids under one agent key
+    (one key may legitimately serve several end users)."""
+
+    def as_dict(self) -> dict[str, Any]:
+        return {
+            "max_turns": self.max_turns,
+            "max_repeats": self.max_repeats,
+            "max_cycle_length": self.max_cycle_length,
+            "window_seconds": self.window_seconds,
+            "max_identical_requests": self.max_identical_requests,
+            "max_repeats_across_sessions": self.max_repeats_across_sessions,
+            "max_duration_seconds": self.max_duration_seconds,
+        }
+
+    def across_sessions(self) -> ConversationPolicy:
+        """The policy applied per principal across sessions: repetition only, no turn cap."""
+        return ConversationPolicy(
+            max_turns=2**31,
+            max_repeats=self.max_repeats_across_sessions,
+            max_cycle_length=self.max_cycle_length,
+            window_seconds=self.window_seconds,
+            max_identical_requests=self.max_repeats_across_sessions,
+            max_repeats_across_sessions=self.max_repeats_across_sessions,
+        )
+
+
+@dataclass
+class _Exchange:
+    request: str
+    reply: str
+    at: float
+
+
+@dataclass
+class ConversationGuard:
+    """Tracks one conversation and decides whether the next request may proceed."""
+
+    policy: ConversationPolicy = field(default_factory=ConversationPolicy)
+    turns: int = 0
+    started_at: float | None = None
+    _history: deque[_Exchange] = field(default_factory=deque)
+
+    def to_dict(self) -> dict[str, Any]:
+        """JSON form, so guards can live in a shared store between requests and workers."""
+        return {
+            "turns": self.turns,
+            "started_at": self.started_at,
+            "history": [[e.request, e.reply, e.at] for e in self._history],
+        }
+
+    @classmethod
+    def from_dict(cls, policy: ConversationPolicy, data: dict[str, Any] | None) -> ConversationGuard:
+        guard = cls(policy)
+        if data:
+            guard.turns = int(data.get("turns", 0))
+            guard.started_at = data.get("started_at")
+            guard._history = deque(_Exchange(r, p, float(t)) for r, p, t in data.get("history", []))
+        return guard
+
+    def _recent(self, now: float) -> list[_Exchange]:
+        cutoff = now - self.policy.window_seconds
+        while self._history and self._history[0].at < cutoff:
+            self._history.popleft()
+        return list(self._history)
+
+    def check(self, request_fp: str, now: float | None = None) -> None:
+        """Raise :class:`ConversationLimitError` if sending ``request_fp`` would continue a loop.
+
+        The request is refused if the conversation is out of turns, or if the
+        last ``max_repeats`` repetitions of some cycle of length ≤ ``max_cycle_length``
+        would be extended by this request with no new information (every
+        exchange in the cycle got the same reply each time).
+        """
+        now = time.time() if now is None else now
+        limit = self.policy.max_duration_seconds
+        if limit is not None and self.started_at is not None and now - self.started_at > limit:
+            raise ConversationLimitError(
+                "conversation_limit",
+                f"this conversation exceeded its time limit of {limit:g}s",
+                {"max_duration_seconds": limit},
+            )
+        if self.turns >= self.policy.max_turns:
+            raise ConversationLimitError(
+                "conversation_limit",
+                f"this conversation reached its limit of {self.policy.max_turns} turns",
+                {"max_turns": self.policy.max_turns},
+            )
+        recent = self._recent(now)
+        identical = 0
+        for exchange in reversed(recent):
+            if exchange.request != request_fp:
+                break
+            identical += 1
+        if identical >= self.policy.max_identical_requests:
+            raise ConversationLimitError(
+                "loop_detected",
+                f"loop detected: the same request was sent {identical} times in a row without converging; "
+                "change the request or stop and report back to the user",
+                {"identical_requests": identical},
+            )
+        repeats = self.policy.max_repeats
+        for period in range(1, self.policy.max_cycle_length + 1):
+            needed = period * repeats
+            if len(recent) < needed:
+                break
+            tail = recent[-needed:]
+            block = tail[:period]
+            if (
+                all(
+                    tail[i].request == block[i % period].request and tail[i].reply == block[i % period].reply
+                    for i in range(needed)
+                )
+                and request_fp == block[0].request
+            ):
+                kind = "the same request" if period == 1 else f"a cycle of {period} requests"
+                raise ConversationLimitError(
+                    "loop_detected",
+                    f"loop detected: {kind} got the same answer {repeats} times in a row; "
+                    "change the request or stop and report back to the user",
+                    {"cycle_length": period, "repeats": repeats},
+                )
+
+    def record(self, request_fp: str, reply_fp: str, now: float | None = None) -> None:
+        now = time.time() if now is None else now
+        if self.started_at is None:
+            self.started_at = now
+        self.turns += 1
+        self._history.append(_Exchange(request_fp, reply_fp, now))
+        max_len = max(self.policy.max_cycle_length * self.policy.max_repeats, self.policy.max_identical_requests)
+        while len(self._history) > max_len:
+            self._history.popleft()
+
+
+__all__ = [
+    "ConversationGuard",
+    "ConversationLimitError",
+    "ConversationPolicy",
+    "fingerprint",
+    "normalize_text",
+    "reply_fingerprint",
+    "request_fingerprint",
+]

wap/spec/crypto.py

@@ -0,0 +1,216 @@
+"""Ed25519 signing, verification and key management for WAP.
+
+Signatures are computed over the RFC 8785 (JSON Canonicalization Scheme) form
+of a document with its ``signature`` member removed (see :mod:`wap.spec.jcs`),
+so any implementation in any language reproduces the exact signed bytes.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, TypeVar
+
+from cryptography.exceptions import InvalidSignature
+from cryptography.hazmat.primitives import serialization
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey, Ed25519PublicKey
+from pydantic import BaseModel
+
+from .jcs import canonicalize
+
+SignedModelT = TypeVar("SignedModelT", bound=BaseModel)
+
+PRIVATE_KEY_ENV = "WAP_PRIVATE_KEY"
+
+
+class KeyFormatError(ValueError):
+    """Raised when key material is not a valid hex-encoded Ed25519 key."""
+
+
+def canonical_json(obj: Any) -> bytes:
+    """Serialise ``obj`` into its RFC 8785 (JCS) canonical bytes, the form WAP signs."""
+    if isinstance(obj, BaseModel):
+        obj = obj.model_dump(mode="json")
+    return canonicalize(obj)
+
+
+def signing_payload(model: BaseModel) -> bytes:
+    """Canonical bytes of ``model`` with its ``signature`` field excluded."""
+    return canonical_json(model.model_dump(mode="json", exclude={"signature"}))
+
+
+def _decode_hex(value: str, length: int, what: str) -> bytes:
+    try:
+        raw = bytes.fromhex(value.strip())
+    except (ValueError, AttributeError) as exc:
+        raise KeyFormatError(f"{what} is not valid hex") from exc
+    if len(raw) != length:
+        raise KeyFormatError(f"{what} must be {length} bytes ({length * 2} hex chars), got {len(raw)}")
+    return raw
+
+
+def load_private_key(private_key_hex: str) -> Ed25519PrivateKey:
+    """Load a raw 32-byte Ed25519 private key (seed) from hex."""
+    return Ed25519PrivateKey.from_private_bytes(_decode_hex(private_key_hex, 32, "private key"))
+
+
+def load_public_key(public_key_hex: str) -> Ed25519PublicKey:
+    """Load a raw 32-byte Ed25519 public key from hex."""
+    return Ed25519PublicKey.from_public_bytes(_decode_hex(public_key_hex, 32, "public key"))
+
+
+def private_key_to_hex(key: Ed25519PrivateKey) -> str:
+    return key.private_bytes(
+        encoding=serialization.Encoding.Raw,
+        format=serialization.PrivateFormat.Raw,
+        encryption_algorithm=serialization.NoEncryption(),
+    ).hex()
+
+
+def public_key_to_hex(key: Ed25519PublicKey) -> str:
+    return key.public_bytes(encoding=serialization.Encoding.Raw, format=serialization.PublicFormat.Raw).hex()
+
+
+def fingerprint(public_key_hex: str) -> str:
+    """Short, human-comparable fingerprint of a public key (``SHA256:<16 hex>``)."""
+    raw = _decode_hex(public_key_hex, 32, "public key")
+    return "SHA256:" + hashlib.sha256(raw).hexdigest()[:32]
+
+
+@dataclass(frozen=True)
+class KeyPair:
+    private_key: str
+    public_key: str
+
+    @property
+    def fingerprint(self) -> str:
+        return fingerprint(self.public_key)
+
+
+def generate_keypair() -> KeyPair:
+    """Generate a fresh Ed25519 key pair, both halves hex-encoded."""
+    key = Ed25519PrivateKey.generate()
+    return KeyPair(private_key=private_key_to_hex(key), public_key=public_key_to_hex(key.public_key()))
+
+
+def sign_bytes(private_key: Ed25519PrivateKey | str, data: bytes) -> str:
+    if isinstance(private_key, str):
+        private_key = load_private_key(private_key)
+    return private_key.sign(data).hex()
+
+
+def verify_bytes(public_key: Ed25519PublicKey | str, data: bytes, signature_hex: str) -> bool:
+    """Return ``True`` iff ``signature_hex`` is a valid signature of ``data``."""
+    try:
+        if isinstance(public_key, str):
+            public_key = load_public_key(public_key)
+        signature = _decode_hex(signature_hex, 64, "signature")
+        public_key.verify(signature, data)
+    except (InvalidSignature, KeyFormatError, ValueError):
+        return False
+    return True
+
+
+def endorsement_payload(manifest: BaseModel) -> bytes:
+    """Bytes a previous key signs to endorse a rotated manifest: everything but the signatures."""
+    return canonical_json(manifest.model_dump(mode="json", exclude={"signature", "key_endorsements"}))
+
+
+def verify_endorsement(manifest: Any, previous_key: str) -> bool:
+    """True iff ``previous_key`` is listed in the manifest and endorsed it."""
+    signature = manifest.key_endorsements.get(previous_key)
+    if previous_key not in manifest.previous_keys or not signature:
+        return False
+    return verify_bytes(previous_key, endorsement_payload(manifest), signature)
+
+
+def sign_model(model: SignedModelT, private_key: Ed25519PrivateKey | str) -> SignedModelT:
+    """Return a copy of ``model`` with its ``signature`` field populated."""
+    if "signature" not in type(model).model_fields:
+        raise TypeError(f"{type(model).__name__} has no signature field")
+    signature = sign_bytes(private_key, signing_payload(model))
+    return model.model_copy(update={"signature": signature})
+
+
+def verify_model(model: BaseModel, public_key: Ed25519PublicKey | str) -> bool:
+    """Verify the embedded ``signature`` of ``model`` against ``public_key``."""
+    signature = getattr(model, "signature", "")
+    if not signature:
+        return False
+    try:
+        payload = signing_payload(model)
+    except ValueError:  # not canonicalisable, so it cannot carry a valid signature
+        return False
+    return verify_bytes(public_key, payload, signature)
+
+
+class Signer:
+    """Holds a private key and signs WAP documents on behalf of an agent."""
+
+    def __init__(self, private_key: Ed25519PrivateKey | str | None = None) -> None:
+        if private_key is None:
+            private_key = Ed25519PrivateKey.generate()
+        elif isinstance(private_key, str):
+            private_key = load_private_key(private_key)
+        self._key = private_key
+        self.public_key = public_key_to_hex(private_key.public_key())
+
+    @classmethod
+    def from_env(cls, variable: str = PRIVATE_KEY_ENV) -> Signer:
+        value = os.environ.get(variable)
+        if not value:
+            raise KeyFormatError(f"environment variable {variable} is not set")
+        return cls(value)
+
+    @classmethod
+    def from_file(cls, path: str | Path) -> Signer:
+        return cls(Path(path).read_text(encoding="utf-8").strip())
+
+    @property
+    def fingerprint(self) -> str:
+        return fingerprint(self.public_key)
+
+    def export_private_key(self) -> str:
+        return private_key_to_hex(self._key)
+
+    def sign(self, data: bytes) -> str:
+        return self._key.sign(data).hex()
+
+    def sign_model(self, model: SignedModelT) -> SignedModelT:
+        return sign_model(model, self._key)
+
+    def derive_secret(self, purpose: str, length: int = 32) -> bytes:
+        """Derive a symmetric secret bound to this key (HKDF-SHA256), e.g. for proof-of-work HMACs.
+
+        Every worker holding the same private key derives the same secret, so no extra
+        secret has to be distributed across a deployment.
+        """
+        from cryptography.hazmat.primitives import hashes
+        from cryptography.hazmat.primitives.kdf.hkdf import HKDF
+
+        seed = bytes.fromhex(self.export_private_key())
+        return HKDF(algorithm=hashes.SHA256(), length=length, salt=None, info=purpose.encode()).derive(seed)
+
+
+__all__ = [
+    "KeyFormatError",
+    "KeyPair",
+    "PRIVATE_KEY_ENV",
+    "Signer",
+    "canonical_json",
+    "fingerprint",
+    "generate_keypair",
+    "load_private_key",
+    "load_public_key",
+    "private_key_to_hex",
+    "public_key_to_hex",
+    "sign_bytes",
+    "endorsement_payload",
+    "sign_model",
+    "verify_endorsement",
+    "signing_payload",
+    "verify_bytes",
+    "verify_model",
+]

wap/spec/jcs.py

@@ -0,0 +1,132 @@
+"""JSON Canonicalization Scheme (RFC 8785).
+
+WAP signs the canonical form of JSON documents so that any implementation, in
+any language, reproduces the exact signed bytes. JCS defines that form:
+
+* objects: members sorted by the UTF-16 code units of their names;
+* no insignificant whitespace;
+* strings: the minimal ECMAScript ``JSON.stringify`` escaping, UTF-8 encoded;
+* numbers: IEEE-754 doubles printed exactly as ECMAScript ``Number.prototype.toString``
+  prints them (shortest round-trip digits; ``1e+21`` style exponents; ``-0`` as ``0``).
+
+Integers outside ±2**53 cannot be represented exactly by a double and are
+rejected, as are NaN and infinities (I-JSON, RFC 7493).
+"""
+
+from __future__ import annotations
+
+import math
+from typing import Any
+
+MAX_SAFE_INTEGER = 2**53
+
+_ESCAPES = {'"': '\\"', "\\": "\\\\", "\b": "\\b", "\f": "\\f", "\n": "\\n", "\r": "\\r", "\t": "\\t"}
+
+
+class CanonicalizationError(ValueError):
+    """The value cannot be represented in canonical JSON."""
+
+
+def _string(value: str) -> str:
+    out = ['"']
+    for ch in value:
+        escaped = _ESCAPES.get(ch)
+        if escaped is not None:
+            out.append(escaped)
+        elif ch < " ":
+            out.append(f"\\u{ord(ch):04x}")
+        else:
+            out.append(ch)
+    out.append('"')
+    return "".join(out)
+
+
+def _number(value: float | int) -> str:
+    if isinstance(value, bool):  # bool is an int subclass; handled by the caller
+        raise CanonicalizationError("booleans are not numbers")
+    if isinstance(value, int):
+        if abs(value) > MAX_SAFE_INTEGER:
+            raise CanonicalizationError(f"integer {value} is outside the IEEE-754 safe range (±2**53)")
+        value = float(value)
+    if not math.isfinite(value):
+        raise CanonicalizationError("NaN and infinities are not valid JSON")
+    if value == 0:
+        return "0"  # also -0
+    sign = "-" if value < 0 else ""
+    # Python's repr is the shortest round-trip representation, like ECMAScript; only the
+    # layout (where the decimal point goes, exponent style) differs, so re-layout the digits.
+    text = repr(abs(value))
+    mantissa, _, exponent = text.partition("e")
+    int_part, _, frac_part = mantissa.partition(".")
+    digits = (int_part + frac_part).lstrip("0")
+    leading_zeros = len(int_part + frac_part) - len((int_part + frac_part).lstrip("0"))
+    point = len(int_part) - leading_zeros + (int(exponent) if exponent else 0)
+    digits = digits.rstrip("0")
+    k, n = len(digits), point
+    if k <= n <= 21:
+        body = digits + "0" * (n - k)
+    elif 0 < n <= 21:
+        body = digits[:n] + "." + digits[n:]
+    elif -6 < n <= 0:
+        body = "0." + "0" * (-n) + digits
+    else:
+        e = n - 1
+        exp = f"e{'+' if e >= 0 else '-'}{abs(e)}"
+        body = (digits + exp) if k == 1 else (digits[0] + "." + digits[1:] + exp)
+    return sign + body
+
+
+def _utf16_key(name: str) -> bytes:
+    return name.encode("utf-16-be", "surrogatepass")
+
+
+def _serialize(value: Any, out: list[str]) -> None:
+    if value is None:
+        out.append("null")
+    elif value is True:
+        out.append("true")
+    elif value is False:
+        out.append("false")
+    elif isinstance(value, str):
+        out.append(_string(value))
+    elif isinstance(value, (int, float)):
+        out.append(_number(value))
+    elif isinstance(value, dict):
+        out.append("{")
+        for i, key in enumerate(sorted(value, key=lambda k: _utf16_key(_check_key(k)))):
+            if i:
+                out.append(",")
+            out.append(_string(key))
+            out.append(":")
+            _serialize(value[key], out)
+        out.append("}")
+    elif isinstance(value, (list, tuple)):
+        out.append("[")
+        for i, item in enumerate(value):
+            if i:
+                out.append(",")
+            _serialize(item, out)
+        out.append("]")
+    else:
+        raise CanonicalizationError(f"{type(value).__name__} is not a JSON type")
+
+
+def _check_key(key: Any) -> str:
+    if not isinstance(key, str):
+        raise CanonicalizationError("object member names must be strings")
+    return key
+
+
+def canonicalize(value: Any) -> bytes:
+    """Return the RFC 8785 canonical UTF-8 bytes of a JSON-compatible Python value."""
+    out: list[str] = []
+    _serialize(value, out)
+    return "".join(out).encode("utf-8", "surrogatepass")
+
+
+def format_number(value: float | int) -> str:
+    """ECMAScript ``Number.prototype.toString`` for a finite double (exposed for tests)."""
+    return _number(value)
+
+
+__all__ = ["CanonicalizationError", "MAX_SAFE_INTEGER", "canonicalize", "format_number"]