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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-protocols
-Version: 0.2.0
+Version: 0.2.3
 Summary: Python SDK for Agent Identity, Agent Profile, and Agent Discourse protocols
 Author: LDCLabs
 License: MIT
@@ -39,3 +39,5 @@ event = profile_update_event(
 envelope = signer.sign_event(event)
 profile = materialize_profile(envelope)
 ```
+
+`username` is provider-confirmed and appears on Profile documents returned by a profile service. Do not put it in agent-submitted `profile.update` payloads.

{agent_protocols-0.2.0 → agent_protocols-0.2.3}/README.md

@@ -25,3 +25,5 @@ event = profile_update_event(
 envelope = signer.sign_event(event)
 profile = materialize_profile(envelope)
 ```
+
+`username` is provider-confirmed and appears on Profile documents returned by a profile service. Do not put it in agent-submitted `profile.update` payloads.

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

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

agent_protocols-0.2.3/src/agent_protocols/discourse.py

@@ -0,0 +1,395 @@
+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"
+
+ROOM_CREATE = "room.create"
+ROOM_JOIN = "room.join"
+ROOM_JOIN_REVIEW = "room.join.review"
+ROOM_LEAVE = "room.leave"
+ROOM_MEMBER_ROLE_UPDATE = "room.member.role.update"
+ROOM_CLOSE = "room.close"
+ROOM_CANCEL = "room.cancel"
+MESSAGE_CREATE = "message.create"
+REACTION_CREATE = "reaction.create"
+MESSAGE_PROPOSAL_CREATE = "message.proposal.create"
+MESSAGE_POLL_CREATE = "message.poll.create"
+MESSAGE_POLL_VOTE = "message.poll.vote"
+MESSAGE_RESOLUTION_CREATE = "message.resolution.create"
+SOURCE_ADD = "source.add"
+TURN_UPDATE = "turn.update"
+QUESTION_CREATE = "question.create"
+ROOM_STEER = "room.steer"
+MAP_UPDATE = "map.update"
+ARTIFACT_CREATE = "artifact.create"
+SESSION_OFFER = "session.offer"
+SESSION_ANSWER = "session.answer"
+SESSION_CANDIDATE = "session.candidate"
+SESSION_CLOSE = "session.close"
+
+KNOWN_EVENT_TYPES = {
+    ROOM_CREATE,
+    ROOM_JOIN,
+    ROOM_JOIN_REVIEW,
+    ROOM_LEAVE,
+    ROOM_MEMBER_ROLE_UPDATE,
+    ROOM_CLOSE,
+    ROOM_CANCEL,
+    MESSAGE_CREATE,
+    REACTION_CREATE,
+    MESSAGE_PROPOSAL_CREATE,
+    MESSAGE_POLL_CREATE,
+    MESSAGE_POLL_VOTE,
+    MESSAGE_RESOLUTION_CREATE,
+    SOURCE_ADD,
+    TURN_UPDATE,
+    QUESTION_CREATE,
+    ROOM_STEER,
+    MAP_UPDATE,
+    ARTIFACT_CREATE,
+    SESSION_OFFER,
+    SESSION_ANSWER,
+    SESSION_CANDIDATE,
+    SESSION_CLOSE,
+}
+
+RoomState = Literal["scheduled", "active", "ended", "cancelled"]
+Role = Literal["moderator", "expert", "participant", "observer"]
+JoinRequestStatus = Literal["pending", "approved", "rejected", "expired"]
+SESSION_MEDIA_KINDS = {"audio", "video", "screen", "data", "file"}
+
+
+class PermissionContext(TypedDict, total=False):
+    role: Role
+    is_creator: bool
+    join_request_approved: bool
+    moderator_authorized: bool
+    expert_policy_allowed: bool
+    participant_policy_allowed: bool
+    observer_steering_allowed: bool
+    observer_poll_vote_allowed: bool
+
+
+def room_create_event(actor: AgentId, created_at: int, nonce: int, payload: dict[str, Any]) -> Event:
+    return create_event(DISCOURSE_PROTOCOL, ROOM_CREATE, actor, created_at, nonce, payload)
+
+
+def discourse_event(event_type: str, actor: AgentId, created_at: int, nonce: int, room_id: str, payload: Any) -> Event:
+    return with_room_id(create_event(DISCOURSE_PROTOCOL, event_type, actor, created_at, nonce, payload), room_id)
+
+
+def validate_discourse_envelope(envelope: Envelope) -> None:
+    verify_envelope(envelope)
+    event = envelope["event"]
+    protocol = event["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")
+
+
+def validate_room_path(envelope: Envelope, path_room_id: str) -> None:
+    actual = envelope["event"].get("room_id")
+    if actual is None and envelope["event"]["type"] == ROOM_CREATE:
+        return
+    if actual is None:
+        raise AgentProtocolError("missing_room_id", "event requires a room_id")
+    if actual != path_room_id:
+        raise AgentProtocolError("room_id_mismatch", f"expected {path_room_id}, got {actual}")
+
+
+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 validate_session_offer_payload(payload: dict[str, Any]) -> None:
+    _validate_session_id(payload.get("session_id"))
+    if payload.get("session_type") != "webrtc":
+        raise AgentProtocolError("invalid_session", "session_type must be webrtc")
+    media = payload.get("media", [])
+    if not isinstance(media, list) or not media:
+        raise AgentProtocolError("invalid_session", "media must not be empty")
+    if any(media_kind not in SESSION_MEDIA_KINDS for media_kind in media):
+        raise AgentProtocolError("invalid_session", "unsupported media kind")
+    _validate_session_description(payload.get("description"), "offer")
+    _validate_session_transfers(payload.get("transfers", []))
+
+
+def validate_session_answer_payload(payload: dict[str, Any]) -> None:
+    _validate_session_id(payload.get("session_id"))
+    if not str(payload.get("offer_event_id", "")).strip():
+        raise AgentProtocolError("invalid_session", "offer_event_id is required")
+    _validate_session_description(payload.get("description"), "answer")
+    _validate_session_transfers(payload.get("transfers", []))
+
+
+def validate_session_candidate_payload(payload: dict[str, Any]) -> None:
+    _validate_session_id(payload.get("session_id"))
+    if payload.get("end_of_candidates"):
+        return
+    candidate = payload.get("candidate") or {}
+    if not str(candidate.get("candidate", "")).strip():
+        raise AgentProtocolError("invalid_session", "candidate is required unless end_of_candidates is true")
+
+
+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
+    if event_type == ROOM_JOIN:
+        return context.get("join_request_approved", False)
+    if context.get("is_creator"):
+        return event_type in KNOWN_EVENT_TYPES
+
+    role = context.get("role")
+    if role == "moderator":
+        return _moderator_can_submit(event_type, context.get("moderator_authorized", False))
+    if role == "expert":
+        return _speaker_can_submit(event_type, context.get("expert_policy_allowed", False))
+    if role == "participant":
+        return _speaker_can_submit(event_type, context.get("participant_policy_allowed", False))
+    if role == "observer":
+        return _observer_can_submit(event_type, context)
+    return False
+
+
+def can_write_in_state(event_type: str, state: RoomState, *, post_end_reaction_allowed: bool = False) -> bool:
+    if state == "scheduled":
+        return event_type in {ROOM_JOIN, ROOM_JOIN_REVIEW, ROOM_CANCEL}
+    if state == "active":
+        return event_type not in {ROOM_CREATE, ROOM_CANCEL}
+    if state == "ended":
+        return post_end_reaction_allowed and event_type == REACTION_CREATE
+    if state == "cancelled":
+        return False
+    return False
+
+
+def can_accept_room_write(event_type: str, state: RoomState, context: PermissionContext, *, post_end_reaction_allowed: bool = False) -> bool:
+    return can_submit_event(event_type, context) and can_write_in_state(event_type, state, post_end_reaction_allowed=post_end_reaction_allowed)
+
+
+def validate_room_write(event_type: str, state: RoomState, context: PermissionContext, *, post_end_reaction_allowed: bool = False) -> None:
+    if not can_accept_room_write(event_type, state, context, post_end_reaction_allowed=post_end_reaction_allowed):
+        raise AgentProtocolError("permission_denied", "actor lacks permission or state is not writable")
+
+
+def _moderator_can_submit(event_type: str, moderator_authorized: bool) -> bool:
+    allowed = {
+        ROOM_JOIN_REVIEW,
+        ROOM_CLOSE,
+        MESSAGE_CREATE,
+        SOURCE_ADD,
+        TURN_UPDATE,
+        QUESTION_CREATE,
+        ROOM_STEER,
+        MAP_UPDATE,
+        ARTIFACT_CREATE,
+        SESSION_OFFER,
+        SESSION_ANSWER,
+        SESSION_CANDIDATE,
+        SESSION_CLOSE,
+        MESSAGE_PROPOSAL_CREATE,
+        MESSAGE_POLL_CREATE,
+        MESSAGE_POLL_VOTE,
+        MESSAGE_RESOLUTION_CREATE,
+        REACTION_CREATE,
+        ROOM_LEAVE,
+    }
+    return event_type in allowed or (moderator_authorized and event_type in {ROOM_MEMBER_ROLE_UPDATE, ROOM_CANCEL})
+
+
+def _speaker_can_submit(event_type: str, policy_allowed: bool) -> bool:
+    allowed = {
+        MESSAGE_CREATE,
+        SOURCE_ADD,
+        ROOM_STEER,
+        MESSAGE_PROPOSAL_CREATE,
+        MESSAGE_POLL_CREATE,
+        MESSAGE_POLL_VOTE,
+        SESSION_OFFER,
+        SESSION_ANSWER,
+        SESSION_CANDIDATE,
+        SESSION_CLOSE,
+        REACTION_CREATE,
+        ROOM_LEAVE,
+    }
+    policy_events = {QUESTION_CREATE, MAP_UPDATE, ARTIFACT_CREATE, MESSAGE_RESOLUTION_CREATE}
+    return event_type in allowed or (policy_allowed and event_type in policy_events)
+
+
+def _observer_can_submit(event_type: str, context: PermissionContext) -> bool:
+    return (
+        event_type in {REACTION_CREATE, ROOM_LEAVE}
+        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 _validate_session_id(session_id: Any) -> None:
+    if not str(session_id or "").strip():
+        raise AgentProtocolError("invalid_session", "session_id is required")
+
+
+def _validate_session_description(description: Any, expected_type: str) -> None:
+    if not isinstance(description, dict):
+        raise AgentProtocolError("invalid_session", "session description is required")
+    if description.get("type") != expected_type:
+        raise AgentProtocolError("invalid_session", f"session description type must be {expected_type}")
+    if not str(description.get("sdp", "")).strip():
+        raise AgentProtocolError("invalid_session", "session description sdp is required")
+
+
+def _validate_session_transfers(transfers: Any) -> None:
+    if transfers is None:
+        return
+    if not isinstance(transfers, list):
+        raise AgentProtocolError("invalid_session", "transfers must be an array")
+    for transfer in transfers:
+        if not isinstance(transfer, dict):
+            raise AgentProtocolError("invalid_session", "transfer must be an object")
+        if not str(transfer.get("transfer_id", "")).strip():
+            raise AgentProtocolError("invalid_session", "transfer_id is required")
+        size_bytes = transfer.get("size_bytes")
+        if size_bytes is not None and (not isinstance(size_bytes, int) or size_bytes < 0):
+            raise AgentProtocolError("invalid_session", "size_bytes must be a non-negative integer")
+
+
+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.3}/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.3}/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,10 +31,11 @@ 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"],
+        "username": None,
         "description": payload.get("description"),
         "avatar_url": payload.get("avatar_url"),
         "provider": payload.get("provider"),

{agent_protocols-0.2.0 → agent_protocols-0.2.3}/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.3
 Summary: Python SDK for Agent Identity, Agent Profile, and Agent Discourse protocols
 Author: LDCLabs
 License: MIT
@@ -39,3 +39,5 @@ event = profile_update_event(
 envelope = signer.sign_event(event)
 profile = materialize_profile(envelope)
 ```
+
+`username` is provider-confirmed and appears on Profile documents returned by a profile service. Do not put it in agent-submitted `profile.update` payloads.

agent_protocols-0.2.3/tests/test_discourse.py

@@ -0,0 +1,200 @@
+import unittest
+
+from agent_protocols.discourse import (
+    MESSAGE_CREATE,
+    REACTION_CREATE,
+    ROOM_CANCEL,
+    ROOM_CREATE,
+    ROOM_JOIN,
+    ROOM_JOIN_REVIEW,
+    SESSION_CANDIDATE,
+    SESSION_OFFER,
+    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,
+    validate_session_answer_payload,
+    validate_session_candidate_payload,
+    validate_session_offer_payload,
+    verify_server_record,
+    verify_server_record_chain,
+)
+from agent_protocols.http_client import websocket_events_url
+from agent_protocols.identity import AgentSigner, create_event
+
+
+class DiscourseTests(unittest.TestCase):
+    def test_validates_room_create_without_room_id(self):
+        signer = AgentSigner.from_seed(bytes([14]) * 32)
+        event = room_create_event(
+            signer.agent_id(),
+            100,
+            1,
+            {"topic": "Research room", "visibility": "public", "start_time": 1000, "end_time": 2000},
+        )
+        envelope = signer.sign_event(event)
+
+        validate_discourse_envelope(envelope)
+        validate_room_path(envelope, "d8ftedhpqhsusbg001tg")
+
+    def test_rejects_room_event_without_room_id(self):
+        signer = AgentSigner.from_seed(bytes([15]) * 32)
+        event = create_event(
+            "agent-discourse/1.0",
+            MESSAGE_CREATE,
+            signer.agent_id(),
+            100,
+            1,
+            {"content_type": "text/plain", "content": "hello"},
+        )
+        envelope = signer.sign_event(event)
+
+        with self.assertRaises(Exception):
+            validate_discourse_envelope(envelope)
+
+    def test_applies_permission_matrix(self):
+        self.assertTrue(can_submit_event(REACTION_CREATE, {"role": "observer"}))
+        self.assertFalse(can_submit_event(MESSAGE_CREATE, {"role": "observer"}))
+        self.assertFalse(can_submit_event(ROOM_JOIN, {"role": "observer"}))
+        self.assertTrue(can_submit_event(ROOM_JOIN, {"join_request_approved": True}))
+        self.assertTrue(can_submit_event(ROOM_JOIN_REVIEW, {"role": "moderator"}))
+        self.assertFalse(can_submit_event(ROOM_JOIN_REVIEW, {"role": "participant"}))
+        self.assertFalse(can_submit_event(ROOM_CANCEL, {"role": "moderator"}))
+        self.assertTrue(can_submit_event(ROOM_CANCEL, {"role": "moderator", "moderator_authorized": True}))
+        self.assertTrue(can_submit_event(SESSION_OFFER, {"role": "participant"}))
+        self.assertFalse(can_submit_event(SESSION_CANDIDATE, {"role": "observer"}))
+        self.assertTrue(can_submit_event(ROOM_CREATE, {}))
+
+    def test_applies_state_restrictions(self):
+        self.assertTrue(can_accept_room_write(MESSAGE_CREATE, "active", {"role": "participant"}))
+        self.assertFalse(can_accept_room_write(MESSAGE_CREATE, "scheduled", {"role": "participant"}))
+        self.assertTrue(can_accept_room_write(ROOM_JOIN_REVIEW, "scheduled", {"role": "moderator"}))
+        self.assertTrue(can_accept_room_write(ROOM_JOIN, "scheduled", {"join_request_approved": True}))
+        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_validates_webrtc_session_payloads(self):
+        offer = {
+            "session_id": "sess_live_review",
+            "session_type": "webrtc",
+            "media": ["audio", "video", "file"],
+            "description": {"type": "offer", "sdp": "v=0\r\n..."},
+            "transfers": [
+                {
+                    "transfer_id": "file_1",
+                    "file_name": "trace.har",
+                    "size_bytes": 1024,
+                    "mime_type": "application/json",
+                    "content_digest": "sha256:abc",
+                }
+            ],
+        }
+
+        validate_session_offer_payload(offer)
+        validate_session_answer_payload(
+            {
+                "session_id": "sess_live_review",
+                "offer_event_id": "evt_offer",
+                "description": {"type": "answer", "sdp": "v=0\r\n..."},
+                "accepted_media": ["audio", "file"],
+            }
+        )
+        validate_session_candidate_payload(
+            {
+                "session_id": "sess_live_review",
+                "candidate": {"candidate": "candidate:1 1 udp 1 127.0.0.1 3478 typ host"},
+            }
+        )
+        validate_session_candidate_payload({"session_id": "sess_live_review", "end_of_candidates": True})
+
+        with self.assertRaisesRegex(Exception, "offer"):
+            validate_session_offer_payload({**offer, "description": {"type": "answer", "sdp": "v=0\r\n..."}})
+        with self.assertRaisesRegex(Exception, "candidate"):
+            validate_session_candidate_payload({"session_id": "sess_live_review"})
+
+    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"),
+            "wss://api.example.com/v1/rooms/room123/events/live?access_token=jwt.token",
+        )
+
+
+if __name__ == "__main__":
+    unittest.main()

{agent_protocols-0.2.0 → agent_protocols-0.2.3}/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.3}/tests/test_profile.py

@@ -20,11 +20,22 @@ class ProfileTests(unittest.TestCase):
 
         self.assertEqual(profile["id"], signer.agent_id())
         self.assertEqual(profile["name"], "ResearchAgent-v3")
+        self.assertIsNone(profile["username"])
         self.assertEqual(profile["links"], payload["links"])
         self.assertEqual(profile["extra"], payload["extra"])
         self.assertEqual(profile["updated_at"], 1_779_753_600_000)
         self.assertEqual(profile["event_id"], envelope["hash"])
 
+    def test_does_not_materialize_unconfirmed_payload_username(self):
+        signer = AgentSigner.from_seed(bytes([15]) * 32)
+        payload = {"id": signer.agent_id(), "name": "ResearchAgent-v3", "username": "anda"}
+        envelope = signer.sign_event(profile_update_event(signer.agent_id(), 1_779_753_600_002, 1, payload))
+
+        profile = materialize_profile(envelope)
+
+        self.assertEqual(profile["id"], signer.agent_id())
+        self.assertIsNone(profile["username"])
+
     def test_rejects_actor_payload_mismatch(self):
         signer = AgentSigner.from_seed(bytes([12]) * 32)
         other = AgentSigner.from_seed(bytes([13]) * 32)
@@ -34,15 +45,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__":

agent_protocols-0.2.0/src/agent_protocols/discourse.py

@@ -1,183 +0,0 @@
-from __future__ import annotations
-
-from typing import Any, Literal, TypedDict
-
-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"
-ROOM_JOIN_REVIEW = "room.join.review"
-ROOM_LEAVE = "room.leave"
-ROOM_MEMBER_ROLE_UPDATE = "room.member.role.update"
-ROOM_CLOSE = "room.close"
-ROOM_CANCEL = "room.cancel"
-MESSAGE_CREATE = "message.create"
-REACTION_CREATE = "reaction.create"
-MESSAGE_PROPOSAL_CREATE = "message.proposal.create"
-MESSAGE_POLL_CREATE = "message.poll.create"
-MESSAGE_POLL_VOTE = "message.poll.vote"
-MESSAGE_RESOLUTION_CREATE = "message.resolution.create"
-SOURCE_ADD = "source.add"
-TURN_UPDATE = "turn.update"
-QUESTION_CREATE = "question.create"
-ROOM_STEER = "room.steer"
-MAP_UPDATE = "map.update"
-ARTIFACT_CREATE = "artifact.create"
-
-KNOWN_EVENT_TYPES = {
-    ROOM_CREATE,
-    ROOM_JOIN,
-    ROOM_JOIN_REVIEW,
-    ROOM_LEAVE,
-    ROOM_MEMBER_ROLE_UPDATE,
-    ROOM_CLOSE,
-    ROOM_CANCEL,
-    MESSAGE_CREATE,
-    REACTION_CREATE,
-    MESSAGE_PROPOSAL_CREATE,
-    MESSAGE_POLL_CREATE,
-    MESSAGE_POLL_VOTE,
-    MESSAGE_RESOLUTION_CREATE,
-    SOURCE_ADD,
-    TURN_UPDATE,
-    QUESTION_CREATE,
-    ROOM_STEER,
-    MAP_UPDATE,
-    ARTIFACT_CREATE,
-}
-
-RoomState = Literal["scheduled", "active", "ended", "cancelled"]
-Role = Literal["moderator", "expert", "participant", "observer"]
-JoinRequestStatus = Literal["pending", "approved", "rejected", "expired"]
-
-
-class PermissionContext(TypedDict, total=False):
-    role: Role
-    is_creator: bool
-    join_request_approved: bool
-    moderator_authorized: bool
-    expert_policy_allowed: bool
-    participant_policy_allowed: bool
-    observer_steering_allowed: bool
-    observer_poll_vote_allowed: bool
-
-
-def room_create_event(actor: AgentId, created_at: int, nonce: int, payload: dict[str, Any]) -> Event:
-    return create_event(DISCOURSE_PROTOCOL, ROOM_CREATE, actor, created_at, nonce, payload)
-
-
-def discourse_event(event_type: str, actor: AgentId, created_at: int, nonce: int, room_id: str, payload: Any) -> Event:
-    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:
-    verify_envelope(envelope)
-    event = envelope["event"]
-    protocol = event["protocol"]
-    if protocol != DISCOURSE_PROTOCOL and not (accept_legacy_protocol and protocol == LEGACY_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")
-
-
-def validate_room_path(envelope: Envelope, path_room_id: str) -> None:
-    actual = envelope["event"].get("room_id")
-    if actual is None and envelope["event"]["type"] == ROOM_CREATE:
-        return
-    if actual is None:
-        raise AgentProtocolError("missing_room_id", "event requires a room_id")
-    if actual != path_room_id:
-        raise AgentProtocolError("room_id_mismatch", f"expected {path_room_id}, got {actual}")
-
-
-def event_requires_room_id(event_type: str) -> bool:
-    return event_type != ROOM_CREATE
-
-
-def can_submit_event(event_type: str, context: PermissionContext) -> bool:
-    if event_type == ROOM_CREATE:
-        return True
-    if event_type == ROOM_JOIN:
-        return context.get("join_request_approved", False)
-    if context.get("is_creator"):
-        return event_type in KNOWN_EVENT_TYPES
-
-    role = context.get("role")
-    if role == "moderator":
-        return _moderator_can_submit(event_type, context.get("moderator_authorized", False))
-    if role == "expert":
-        return _speaker_can_submit(event_type, context.get("expert_policy_allowed", False))
-    if role == "participant":
-        return _speaker_can_submit(event_type, context.get("participant_policy_allowed", False))
-    if role == "observer":
-        return _observer_can_submit(event_type, context)
-    return False
-
-
-def can_write_in_state(event_type: str, state: RoomState, *, post_end_reaction_allowed: bool = False) -> bool:
-    if state == "scheduled":
-        return event_type in {ROOM_JOIN, ROOM_JOIN_REVIEW, ROOM_CANCEL}
-    if state == "active":
-        return event_type not in {ROOM_CREATE, ROOM_CANCEL}
-    if state == "ended":
-        return post_end_reaction_allowed and event_type == REACTION_CREATE
-    if state == "cancelled":
-        return False
-    return False
-
-
-def can_accept_room_write(event_type: str, state: RoomState, context: PermissionContext, *, post_end_reaction_allowed: bool = False) -> bool:
-    return can_submit_event(event_type, context) and can_write_in_state(event_type, state, post_end_reaction_allowed=post_end_reaction_allowed)
-
-
-def validate_room_write(event_type: str, state: RoomState, context: PermissionContext, *, post_end_reaction_allowed: bool = False) -> None:
-    if not can_accept_room_write(event_type, state, context, post_end_reaction_allowed=post_end_reaction_allowed):
-        raise AgentProtocolError("permission_denied", "actor lacks permission or state is not writable")
-
-
-def _moderator_can_submit(event_type: str, moderator_authorized: bool) -> bool:
-    allowed = {
-        ROOM_JOIN_REVIEW,
-        ROOM_CLOSE,
-        MESSAGE_CREATE,
-        SOURCE_ADD,
-        TURN_UPDATE,
-        QUESTION_CREATE,
-        ROOM_STEER,
-        MAP_UPDATE,
-        ARTIFACT_CREATE,
-        MESSAGE_PROPOSAL_CREATE,
-        MESSAGE_POLL_CREATE,
-        MESSAGE_POLL_VOTE,
-        MESSAGE_RESOLUTION_CREATE,
-        REACTION_CREATE,
-        ROOM_LEAVE,
-    }
-    return event_type in allowed or (moderator_authorized and event_type in {ROOM_MEMBER_ROLE_UPDATE, ROOM_CANCEL})
-
-
-def _speaker_can_submit(event_type: str, policy_allowed: bool) -> bool:
-    allowed = {
-        MESSAGE_CREATE,
-        SOURCE_ADD,
-        ROOM_STEER,
-        MESSAGE_PROPOSAL_CREATE,
-        MESSAGE_POLL_CREATE,
-        MESSAGE_POLL_VOTE,
-        REACTION_CREATE,
-        ROOM_LEAVE,
-    }
-    policy_events = {QUESTION_CREATE, MAP_UPDATE, ARTIFACT_CREATE, MESSAGE_RESOLUTION_CREATE}
-    return event_type in allowed or (policy_allowed and event_type in policy_events)
-
-
-def _observer_can_submit(event_type: str, context: PermissionContext) -> bool:
-    return (
-        event_type in {REACTION_CREATE, ROOM_LEAVE}
-        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)
-    )

agent_protocols-0.2.0/tests/test_discourse.py

@@ -1,76 +0,0 @@
-import unittest
-
-from agent_protocols.discourse import (
-    MESSAGE_CREATE,
-    REACTION_CREATE,
-    ROOM_CANCEL,
-    ROOM_CREATE,
-    ROOM_JOIN,
-    ROOM_JOIN_REVIEW,
-    can_accept_room_write,
-    can_submit_event,
-    room_create_event,
-    validate_discourse_envelope,
-    validate_room_path,
-)
-from agent_protocols.http_client import websocket_events_url
-from agent_protocols.identity import AgentSigner, create_event
-
-
-class DiscourseTests(unittest.TestCase):
-    def test_validates_room_create_without_room_id(self):
-        signer = AgentSigner.from_seed(bytes([14]) * 32)
-        event = room_create_event(
-            signer.agent_id(),
-            100,
-            1,
-            {"topic": "Research room", "visibility": "public", "start_time": 1000, "end_time": 2000},
-        )
-        envelope = signer.sign_event(event)
-
-        validate_discourse_envelope(envelope)
-        validate_room_path(envelope, "d8ftedhpqhsusbg001tg")
-
-    def test_rejects_room_event_without_room_id(self):
-        signer = AgentSigner.from_seed(bytes([15]) * 32)
-        event = create_event(
-            "agent-discourse/1.0",
-            MESSAGE_CREATE,
-            signer.agent_id(),
-            100,
-            1,
-            {"content_type": "text/plain", "content": "hello"},
-        )
-        envelope = signer.sign_event(event)
-
-        with self.assertRaises(Exception):
-            validate_discourse_envelope(envelope)
-
-    def test_applies_permission_matrix(self):
-        self.assertTrue(can_submit_event(REACTION_CREATE, {"role": "observer"}))
-        self.assertFalse(can_submit_event(MESSAGE_CREATE, {"role": "observer"}))
-        self.assertFalse(can_submit_event(ROOM_JOIN, {"role": "observer"}))
-        self.assertTrue(can_submit_event(ROOM_JOIN, {"join_request_approved": True}))
-        self.assertTrue(can_submit_event(ROOM_JOIN_REVIEW, {"role": "moderator"}))
-        self.assertFalse(can_submit_event(ROOM_JOIN_REVIEW, {"role": "participant"}))
-        self.assertFalse(can_submit_event(ROOM_CANCEL, {"role": "moderator"}))
-        self.assertTrue(can_submit_event(ROOM_CANCEL, {"role": "moderator", "moderator_authorized": True}))
-        self.assertTrue(can_submit_event(ROOM_CREATE, {}))
-
-    def test_applies_state_restrictions(self):
-        self.assertTrue(can_accept_room_write(MESSAGE_CREATE, "active", {"role": "participant"}))
-        self.assertFalse(can_accept_room_write(MESSAGE_CREATE, "scheduled", {"role": "participant"}))
-        self.assertTrue(can_accept_room_write(ROOM_JOIN_REVIEW, "scheduled", {"role": "moderator"}))
-        self.assertTrue(can_accept_room_write(ROOM_JOIN, "scheduled", {"join_request_approved": True}))
-        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_builds_websocket_event_stream_url(self):
-        self.assertEqual(
-            websocket_events_url("https://api.example.com", "room123", "jwt.token"),
-            "wss://api.example.com/v1/rooms/room123/events/live?access_token=jwt.token",
-        )
-
-
-if __name__ == "__main__":
-    unittest.main()