agent-protocols 0.2.0__tar.gz → 0.2.2__tar.gz

{agent_protocols-0.2.0 → agent_protocols-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-protocols
-Version: 0.2.0
+Version: 0.2.2
 Summary: Python SDK for Agent Identity, Agent Profile, and Agent Discourse protocols
 Author: LDCLabs
 License: MIT

{agent_protocols-0.2.0 → agent_protocols-0.2.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agent-protocols"
-version = "0.2.0"
+version = "0.2.2"
 description = "Python SDK for Agent Identity, Agent Profile, and Agent Discourse protocols"
 readme = "README.md"
 requires-python = ">=3.10"

{agent_protocols-0.2.0 → agent_protocols-0.2.2}/src/agent_protocols/discourse.py

@@ -1,12 +1,15 @@
 from __future__ import annotations
 
+import base64
+import hashlib
 from typing import Any, Literal, TypedDict
 
+import rfc8785
+
 from .errors import AgentProtocolError
 from .identity import AgentId, Envelope, Event, create_event, verify_envelope, with_room_id
 
 DISCOURSE_PROTOCOL = "agent-discourse/1.0"
-LEGACY_DISCOURSE_PROTOCOL = "adp/1.0"
 
 ROOM_CREATE = "room.create"
 ROOM_JOIN = "room.join"
@@ -74,11 +77,11 @@ def discourse_event(event_type: str, actor: AgentId, created_at: int, nonce: int
     return with_room_id(create_event(DISCOURSE_PROTOCOL, event_type, actor, created_at, nonce, payload), room_id)
 
 
-def validate_discourse_envelope(envelope: Envelope, accept_legacy_protocol: bool = False) -> None:
+def validate_discourse_envelope(envelope: Envelope) -> None:
     verify_envelope(envelope)
     event = envelope["event"]
     protocol = event["protocol"]
-    if protocol != DISCOURSE_PROTOCOL and not (accept_legacy_protocol and protocol == LEGACY_DISCOURSE_PROTOCOL):
+    if protocol != DISCOURSE_PROTOCOL:
         raise AgentProtocolError("invalid_event_protocol", f"expected {DISCOURSE_PROTOCOL}, got {protocol}")
     if event_requires_room_id(event["type"]) and "room_id" not in event:
         raise AgentProtocolError("missing_room_id", "event requires a room_id")
@@ -98,6 +101,132 @@ def event_requires_room_id(event_type: str) -> bool:
     return event_type != ROOM_CREATE
 
 
+def validate_room_create_payload(payload: dict[str, Any]) -> None:
+    if not str(payload.get("topic", "")).strip():
+        raise AgentProtocolError("invalid_room", "room topic must not be empty")
+    if payload.get("start_time", 0) >= payload.get("end_time", 0):
+        raise AgentProtocolError("invalid_room", "start_time must be before end_time")
+    policy = payload.get("policy") or {}
+    max_participants = policy.get("max_participants")
+    if max_participants is not None and (
+        not isinstance(max_participants, int) or max_participants < 1
+    ):
+        raise AgentProtocolError("invalid_room", "max_participants must be a positive integer")
+
+
+def validate_poll_create_payload(payload: dict[str, Any]) -> None:
+    if not str(payload.get("poll_id", "")).strip() or not str(payload.get("question", "")).strip():
+        raise AgentProtocolError("invalid_poll", "poll_id and question are required")
+    options = payload.get("options", [])
+    if len(options) < 2:
+        raise AgentProtocolError("invalid_poll", "poll requires at least two options")
+    option_ids: set[str] = set()
+    for option in options:
+        option_id = str(option.get("id", ""))
+        label = str(option.get("label", ""))
+        if not option_id.strip() or not label.strip():
+            raise AgentProtocolError("invalid_poll", "option id and label are required")
+        if option_id in option_ids:
+            raise AgentProtocolError("invalid_poll", "poll option ids must be unique")
+        option_ids.add(option_id)
+    min_choices = payload.get("min_choices", 1)
+    max_choices = payload.get("max_choices", 1)
+    if min_choices < 1 or max_choices < min_choices:
+        raise AgentProtocolError("invalid_poll", "invalid poll choice limits")
+
+
+def validate_poll_vote_payload(payload: dict[str, Any], poll: dict[str, Any], now_ms: int | None = None) -> None:
+    if poll.get("closes_at") is not None and now_ms is not None and now_ms > poll["closes_at"]:
+        raise AgentProtocolError("poll_closed", "poll is closed")
+    min_choices = poll.get("min_choices", 1)
+    max_choices = poll.get("max_choices", 1)
+    option_ids = {option["id"] for option in poll.get("options", [])}
+    selected = payload.get("option_ids", [])
+    selected_set = set(selected)
+    if len(selected_set) != len(selected):
+        raise AgentProtocolError("invalid_poll_vote", "duplicate poll options")
+    if len(selected_set) < min_choices or len(selected_set) > max_choices:
+        raise AgentProtocolError("invalid_poll_vote", "invalid number of options")
+    if any(option_id not in option_ids for option_id in selected_set):
+        raise AgentProtocolError("invalid_poll_vote", "unknown poll option")
+
+
+def server_record_hash_payload(
+    room_id: str,
+    seq: int,
+    pre_hash: str | None,
+    envelope_hash: str,
+    received_at: int,
+) -> dict[str, Any]:
+    return {
+        "room_id": room_id,
+        "seq": seq,
+        "pre_hash": pre_hash,
+        "envelope_hash": envelope_hash,
+        "received_at": received_at,
+    }
+
+
+def server_record_hash(
+    room_id: str,
+    seq: int,
+    pre_hash: str | None,
+    envelope_hash: str,
+    received_at: int,
+) -> str:
+    return _hash_canonical_json(server_record_hash_payload(room_id, seq, pre_hash, envelope_hash, received_at))
+
+
+def build_server_record(
+    room_id: str,
+    seq: int,
+    pre_hash: str | None,
+    received_at: int,
+    envelope: Envelope,
+) -> dict[str, Any]:
+    return {
+        "room_id": room_id,
+        "seq": seq,
+        "pre_hash": pre_hash,
+        "hash": server_record_hash(room_id, seq, pre_hash, envelope["hash"], received_at),
+        "received_at": received_at,
+        "envelope": envelope,
+    }
+
+
+def verify_server_record(record: dict[str, Any]) -> None:
+    expected = server_record_hash(
+        record["room_id"],
+        record["seq"],
+        record.get("pre_hash"),
+        record["envelope"]["hash"],
+        record["received_at"],
+    )
+    if record["hash"] != expected:
+        raise AgentProtocolError("invalid_record_hash", f"invalid server record hash: expected {expected}, got {record['hash']}")
+
+
+def verify_server_record_chain(records: list[dict[str, Any]]) -> None:
+    previous: dict[str, Any] | None = None
+    for record in records:
+        verify_server_record(record)
+        if previous is None:
+            if record["seq"] != 1:
+                raise AgentProtocolError("invalid_record_chain", "first seq must be 1")
+            if record.get("pre_hash") is not None:
+                raise AgentProtocolError("invalid_record_chain", "first pre_hash must be null")
+        else:
+            if record["seq"] != previous["seq"] + 1:
+                raise AgentProtocolError("invalid_record_chain", "seq must increase by 1")
+            if record.get("pre_hash") != previous["hash"]:
+                raise AgentProtocolError("invalid_record_chain", "pre_hash mismatch")
+        previous = record
+
+
+def archive_events_digest(records: list[dict[str, Any]]) -> str:
+    return _hash_canonical_json(records)
+
+
 def can_submit_event(event_type: str, context: PermissionContext) -> bool:
     if event_type == ROOM_CREATE:
         return True
@@ -181,3 +310,10 @@ def _observer_can_submit(event_type: str, context: PermissionContext) -> bool:
         or (context.get("observer_steering_allowed", False) and event_type == ROOM_STEER)
         or (context.get("observer_poll_vote_allowed", False) and event_type == MESSAGE_POLL_VOTE)
     )
+
+
+def _hash_canonical_json(value: Any) -> str:
+    canonical = rfc8785.dumps(value)
+    data = canonical if isinstance(canonical, bytes) else canonical.encode()
+    digest = hashlib.sha3_256(data).digest()
+    return base64.urlsafe_b64encode(digest).rstrip(b"=").decode()

{agent_protocols-0.2.0 → agent_protocols-0.2.2}/src/agent_protocols/identity.py

@@ -20,6 +20,7 @@ DEFAULT_LIVE_WRITE_WINDOW_MS = 300_000
 DEFAULT_NONCE_TTL_MS = 300_000
 DEFAULT_REQUEST_JWT_TTL_SECS = 300
 MAX_NONCE_HEADER = "Max-Seen-Nonce"
+MAX_SAFE_NONCE = 0x1FFFFFFFFFFFFF
 
 Event = dict[str, Any]
 Envelope = dict[str, Any]
@@ -134,6 +135,7 @@ class ClientNonceManager:
 
     def next_nonce(self) -> int:
         nonce = self._next_nonce
+        validate_nonce(nonce)
         self._next_nonce += 1
         return nonce
 
@@ -174,11 +176,13 @@ def canonical_event_bytes(event: Event) -> bytes:
 
 
 def event_hash(event: Event) -> str:
+    validate_nonce(event["nonce"])
     digest = hashlib.sha3_256(canonical_event_bytes(event)).digest()
     return _base64url_encode(digest)
 
 
 def sign_event(private_key: Ed25519PrivateKey, event: Event) -> str:
+    validate_nonce(event["nonce"])
     return _base64url_encode(private_key.sign(canonical_event_bytes(event)))
 
 
@@ -253,6 +257,8 @@ def verify_request_jwt(token: str, *, audience: str, now_secs: int | None = None
         raise AgentProtocolError("invalid_jwt_claim", "aud mismatch")
 
     now = now_secs if now_secs is not None else unix_secs()
+    if claims["exp"] <= claims["iat"]:
+        raise AgentProtocolError("invalid_jwt_claim", "exp must be greater than iat")
     if claims["iat"] > now or claims["exp"] < now:
         raise AgentProtocolError("invalid_jwt_claim", "iat/exp outside valid time window")
     if claims["exp"] - claims["iat"] > max_ttl_secs:
@@ -269,7 +275,7 @@ def unix_secs() -> int:
 
 
 def validate_nonce(nonce: int) -> None:
-    if not isinstance(nonce, int) or nonce < 1 or nonce > 0x1FFFFFFFFFFFFF:
+    if not isinstance(nonce, int) or nonce < 1 or nonce > MAX_SAFE_NONCE:
         raise AgentProtocolError("invalid_nonce", "nonce must be a positive integer less than or equal to 9007199254740991")
 
 

{agent_protocols-0.2.0 → agent_protocols-0.2.2}/src/agent_protocols/profile.py

@@ -19,7 +19,7 @@ def profile_update_event(actor: AgentId, created_at: int, nonce: int, payload: P
 def validate_profile_update(envelope: Envelope) -> None:
     verify_envelope(envelope)
     event = envelope["event"]
-    payload_id = event["payload"].get("id") or event["payload"].get("agent_id")
+    payload_id = event["payload"].get("id")
     if event["protocol"] != PROFILE_PROTOCOL:
         raise AgentProtocolError("invalid_event_protocol", f"expected {PROFILE_PROTOCOL}, got {event['protocol']}")
     if event["type"] != PROFILE_UPDATE:
@@ -31,7 +31,7 @@ def validate_profile_update(envelope: Envelope) -> None:
 def materialize_profile(envelope: Envelope) -> AgentProfile:
     validate_profile_update(envelope)
     payload = envelope["event"]["payload"]
-    payload_id = payload.get("id") or payload.get("agent_id")
+    payload_id = payload.get("id")
     return {
         "id": payload_id,
         "name": payload["name"],

{agent_protocols-0.2.0 → agent_protocols-0.2.2}/src/agent_protocols.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-protocols
-Version: 0.2.0
+Version: 0.2.2
 Summary: Python SDK for Agent Identity, Agent Profile, and Agent Discourse protocols
 Author: LDCLabs
 License: MIT

{agent_protocols-0.2.0 → agent_protocols-0.2.2}/tests/test_discourse.py

@@ -7,11 +7,19 @@ from agent_protocols.discourse import (
     ROOM_CREATE,
     ROOM_JOIN,
     ROOM_JOIN_REVIEW,
+    archive_events_digest,
+    build_server_record,
     can_accept_room_write,
     can_submit_event,
     room_create_event,
+    server_record_hash,
+    validate_poll_create_payload,
+    validate_poll_vote_payload,
     validate_discourse_envelope,
+    validate_room_create_payload,
     validate_room_path,
+    verify_server_record,
+    verify_server_record_chain,
 )
 from agent_protocols.http_client import websocket_events_url
 from agent_protocols.identity import AgentSigner, create_event
@@ -65,6 +73,76 @@ class DiscourseTests(unittest.TestCase):
         self.assertFalse(can_accept_room_write(REACTION_CREATE, "ended", {"role": "participant"}))
         self.assertTrue(can_accept_room_write(REACTION_CREATE, "ended", {"role": "participant"}, post_end_reaction_allowed=True))
 
+    def test_validates_room_creation_payloads(self):
+        validate_room_create_payload(
+            {
+                "topic": "Research room",
+                "visibility": "public",
+                "start_time": 1000,
+                "end_time": 2000,
+                "policy": {"max_participants": 2},
+            }
+        )
+        with self.assertRaises(Exception):
+            validate_room_create_payload({"topic": " ", "visibility": "public", "start_time": 1000, "end_time": 2000})
+        with self.assertRaises(Exception):
+            validate_room_create_payload(
+                {"topic": "Research room", "visibility": "public", "start_time": 2000, "end_time": 1000}
+            )
+
+    def test_validates_poll_payloads_and_votes(self):
+        poll = {
+            "poll_id": "poll_review_order",
+            "question": "Which review order?",
+            "options": [{"id": "a", "label": "Correctness first"}, {"id": "b", "label": "Security first"}],
+            "min_choices": 1,
+            "max_choices": 1,
+        }
+
+        validate_poll_create_payload(poll)
+        validate_poll_vote_payload({"event_id": "evt", "option_ids": ["a"]}, poll)
+        with self.assertRaises(Exception):
+            validate_poll_vote_payload({"event_id": "evt", "option_ids": ["a", "b"]}, poll)
+        with self.assertRaises(Exception):
+            validate_poll_create_payload(
+                {
+                    **poll,
+                    "options": [{"id": "a", "label": "Correctness first"}, {"id": "a", "label": "Duplicate"}],
+                }
+            )
+
+    def test_builds_and_verifies_server_record_chains(self):
+        signer = AgentSigner.from_seed(bytes([18]) * 32)
+        envelope1 = signer.sign_event(
+            room_create_event(
+                signer.agent_id(),
+                100,
+                1,
+                {"topic": "Research room", "visibility": "public", "start_time": 1000, "end_time": 2000},
+            )
+        )
+        record1 = build_server_record("room123", 1, None, 110, envelope1)
+        event2 = create_event(
+            "agent-discourse/1.0",
+            MESSAGE_CREATE,
+            signer.agent_id(),
+            120,
+            2,
+            {"content_type": "text/plain", "content": "hello"},
+        )
+        event2["room_id"] = "room123"
+        envelope2 = signer.sign_event(event2)
+        record2 = build_server_record("room123", 2, record1["hash"], 130, envelope2)
+
+        self.assertEqual(record1["hash"], server_record_hash("room123", 1, None, envelope1["hash"], 110))
+        verify_server_record(record1)
+        verify_server_record_chain([record1, record2])
+        self.assertEqual(len(archive_events_digest([record1, record2])), 43)
+        with self.assertRaisesRegex(Exception, "first seq"):
+            verify_server_record_chain([record2])
+        with self.assertRaises(Exception):
+            verify_server_record_chain([{**record2, "pre_hash": "bad"}])
+
     def test_builds_websocket_event_stream_url(self):
         self.assertEqual(
             websocket_events_url("https://api.example.com", "room123", "jwt.token"),

{agent_protocols-0.2.0 → agent_protocols-0.2.2}/tests/test_identity.py

@@ -3,6 +3,7 @@ import unittest
 from agent_protocols.identity import (
     AgentSigner,
     ClientNonceManager,
+    MAX_SAFE_NONCE,
     MemoryNonceStore,
     RequestBinding,
     create_event,
@@ -22,7 +23,7 @@ class IdentityTests(unittest.TestCase):
             signer.agent_id(),
             1_779_753_600_000,
             1,
-            {"agent_id": signer.agent_id(), "name": "ResearchAgent"},
+            {"id": signer.agent_id(), "name": "ResearchAgent"},
         )
 
         envelope = signer.sign_event(event)
@@ -61,6 +62,19 @@ class IdentityTests(unittest.TestCase):
         self.assertEqual(manager.peek(), 6)
         self.assertEqual(manager.next_nonce(), 6)
 
+    def test_rejects_nonce_values_outside_safe_json_integer_range(self):
+        signer = AgentSigner.from_seed(bytes([16]) * 32)
+
+        with self.assertRaises(Exception):
+            create_event(
+                "agent-profile/1.0",
+                "profile.update",
+                signer.agent_id(),
+                1000,
+                MAX_SAFE_NONCE + 1,
+                {"id": signer.agent_id(), "name": "ResearchAgent"},
+            )
+
     def test_signs_and_verifies_request_jwts(self):
         signer = AgentSigner.from_seed(bytes([10]) * 32)
         binding = RequestBinding.create("https://api.example.com")
@@ -76,6 +90,20 @@ class IdentityTests(unittest.TestCase):
 
         self.assertEqual(verified["iss"], signer.agent_id())
 
+    def test_rejects_request_jwts_with_non_positive_ttl(self):
+        signer = AgentSigner.from_seed(bytes([17]) * 32)
+        binding = RequestBinding.create("https://api.example.com")
+        claims = create_request_jwt_claims(signer.agent_id(), binding, 100, 0)
+        token = signer.sign_request_jwt(claims)
+
+        with self.assertRaises(Exception):
+            verify_request_jwt(
+                token,
+                audience=binding.audience,
+                now_secs=100,
+                max_ttl_secs=300,
+            )
+
 
 if __name__ == "__main__":
     unittest.main()

{agent_protocols-0.2.0 → agent_protocols-0.2.2}/tests/test_profile.py

@@ -34,15 +34,13 @@ class ProfileTests(unittest.TestCase):
         with self.assertRaises(Exception):
             validate_profile_update(envelope)
 
-    def test_materializes_legacy_agent_id_payload(self):
+    def test_rejects_legacy_agent_id_payload_without_id(self):
         signer = AgentSigner.from_seed(bytes([14]) * 32)
         payload = {"agent_id": signer.agent_id(), "name": "LegacyAgent"}
         envelope = signer.sign_event(profile_update_event(signer.agent_id(), 1_779_753_600_001, 1, payload))
 
-        profile = materialize_profile(envelope)
-
-        self.assertEqual(profile["id"], signer.agent_id())
-        self.assertEqual(profile["name"], "LegacyAgent")
+        with self.assertRaises(Exception):
+            materialize_profile(envelope)
 
 
 if __name__ == "__main__":