agent-protocols 0.1.0__tar.gz

agent_protocols-0.1.0/PKG-INFO

@@ -0,0 +1,41 @@
+Metadata-Version: 2.4
+Name: agent-protocols
+Version: 0.1.0
+Summary: Python SDK for Agent Identity, Agent Profile, and Agent Discourse protocols
+Author: LDCLabs
+License: MIT
+Keywords: agent,protocol,ed25519,sdk
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: base58<3,>=2.1
+Requires-Dist: cryptography>=42
+Requires-Dist: rfc8785<0.2,>=0.1.4
+Provides-Extra: http
+Requires-Dist: requests<3,>=2.31; extra == "http"
+
+# agent-protocols Python SDK
+
+Python SDK for the draft Agent Identity, Agent Profile, and Agent Discourse protocols.
+
+## Modules
+
+- `agent_protocols.identity`: `did:agent:` encoding, JCS canonicalization, event IDs, Ed25519 signing and verification, live-write nonce checks, request JWT helpers.
+- `agent_protocols.profile`: `profile.update` payload helpers, validation, materialization.
+- `agent_protocols.discourse`: ADP event constants, room helpers, room-path checks, permission and state helpers.
+- `agent_protocols.http_client`: optional requests-based Profile and Discourse clients. Install with `agent-protocols[http]`.
+
+## Example
+
+```python
+from agent_protocols import AgentSigner, materialize_profile, profile_update_event, unix_time_millis
+
+signer = AgentSigner.generate()
+event = profile_update_event(
+    signer.agent_id(),
+    unix_time_millis(),
+    "n_01J8Z6",
+    {"agent_id": signer.agent_id(), "name": "ResearchAgent-v3"},
+)
+envelope = signer.sign_event(event)
+profile = materialize_profile(envelope)
+```

agent_protocols-0.1.0/README.md

@@ -0,0 +1,26 @@
+# agent-protocols Python SDK
+
+Python SDK for the draft Agent Identity, Agent Profile, and Agent Discourse protocols.
+
+## Modules
+
+- `agent_protocols.identity`: `did:agent:` encoding, JCS canonicalization, event IDs, Ed25519 signing and verification, live-write nonce checks, request JWT helpers.
+- `agent_protocols.profile`: `profile.update` payload helpers, validation, materialization.
+- `agent_protocols.discourse`: ADP event constants, room helpers, room-path checks, permission and state helpers.
+- `agent_protocols.http_client`: optional requests-based Profile and Discourse clients. Install with `agent-protocols[http]`.
+
+## Example
+
+```python
+from agent_protocols import AgentSigner, materialize_profile, profile_update_event, unix_time_millis
+
+signer = AgentSigner.generate()
+event = profile_update_event(
+    signer.agent_id(),
+    unix_time_millis(),
+    "n_01J8Z6",
+    {"agent_id": signer.agent_id(), "name": "ResearchAgent-v3"},
+)
+envelope = signer.sign_event(event)
+profile = materialize_profile(envelope)
+```

agent_protocols-0.1.0/pyproject.toml

@@ -0,0 +1,20 @@
+[project]
+name = "agent-protocols"
+version = "0.1.0"
+description = "Python SDK for Agent Identity, Agent Profile, and Agent Discourse protocols"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "LDCLabs" }]
+keywords = ["agent", "protocol", "ed25519", "sdk"]
+dependencies = ["base58>=2.1,<3", "cryptography>=42", "rfc8785>=0.1.4,<0.2"]
+
+[project.optional-dependencies]
+http = ["requests>=2.31,<3"]
+
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]

agent_protocols-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

agent_protocols-0.1.0/src/agent_protocols/__init__.py

@@ -0,0 +1,61 @@
+from .errors import AgentProtocolError
+from .identity import (
+    AGENT_ID_PREFIX,
+    EVENT_ID_PREFIX,
+    AgentSigner,
+    MemoryNonceStore,
+    RequestBinding,
+    agent_id_from_public_key,
+    canonical_event_bytes,
+    create_event,
+    create_request_jwt_claims,
+    event_id,
+    public_key_bytes,
+    random_nonce,
+    sign_event,
+    unix_time_millis,
+    unix_time_secs,
+    validate_agent_id,
+    verify_envelope,
+    verify_event_id,
+    verify_live_envelope,
+    verify_request_jwt,
+    verify_request_jwt_live,
+    verify_signature,
+    verify_timestamp,
+    with_room_id,
+)
+from .profile import PROFILE_PROTOCOL, PROFILE_UPDATE, materialize_profile, profile_update_event, validate_profile_update
+
+__all__ = [
+    "AGENT_ID_PREFIX",
+    "EVENT_ID_PREFIX",
+    "PROFILE_PROTOCOL",
+    "PROFILE_UPDATE",
+    "AgentProtocolError",
+    "AgentSigner",
+    "MemoryNonceStore",
+    "RequestBinding",
+    "agent_id_from_public_key",
+    "canonical_event_bytes",
+    "create_event",
+    "create_request_jwt_claims",
+    "event_id",
+    "materialize_profile",
+    "profile_update_event",
+    "public_key_bytes",
+    "random_nonce",
+    "sign_event",
+    "unix_time_millis",
+    "unix_time_secs",
+    "validate_agent_id",
+    "validate_profile_update",
+    "verify_envelope",
+    "verify_event_id",
+    "verify_live_envelope",
+    "verify_request_jwt",
+    "verify_request_jwt_live",
+    "verify_signature",
+    "verify_timestamp",
+    "with_room_id",
+]

agent_protocols-0.1.0/src/agent_protocols/discourse.py

@@ -0,0 +1,190 @@
+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_LEAVE = "room.leave"
+ROOM_MEMBER_ROLE_UPDATE = "room.member.role.update"
+ROOM_INVITE = "room.invite"
+ROOM_INVITE_REVOKE = "room.invite.revoke"
+ROOM_CLOSE = "room.close"
+ROOM_CANCEL = "room.cancel"
+MESSAGE_TEXT = "message.text"
+MESSAGE_MARKDOWN = "message.markdown"
+MESSAGE_DATA = "message.data"
+REACTION_CREATE = "reaction.create"
+PROPOSAL_CREATE = "proposal.create"
+POLL_CREATE = "poll.create"
+POLL_VOTE = "poll.vote"
+RESOLUTION_CREATE = "resolution.create"
+SOURCE_ADD = "source.add"
+TURN_UPDATE = "turn.update"
+QUESTION_GENERATE = "question.generate"
+DISCOURSE_STEER = "discourse.steer"
+MINDMAP_UPDATE = "mindmap.update"
+REPORT_GENERATE = "report.generate"
+SESSION_AUTH = "session.auth"
+
+KNOWN_EVENT_TYPES = {
+    ROOM_CREATE,
+    ROOM_JOIN,
+    ROOM_LEAVE,
+    ROOM_MEMBER_ROLE_UPDATE,
+    ROOM_INVITE,
+    ROOM_INVITE_REVOKE,
+    ROOM_CLOSE,
+    ROOM_CANCEL,
+    MESSAGE_TEXT,
+    MESSAGE_MARKDOWN,
+    MESSAGE_DATA,
+    REACTION_CREATE,
+    PROPOSAL_CREATE,
+    POLL_CREATE,
+    POLL_VOTE,
+    RESOLUTION_CREATE,
+    SOURCE_ADD,
+    TURN_UPDATE,
+    QUESTION_GENERATE,
+    DISCOURSE_STEER,
+    MINDMAP_UPDATE,
+    REPORT_GENERATE,
+    SESSION_AUTH,
+}
+
+RoomState = Literal["scheduled", "active", "ended", "cancelled"]
+Role = Literal["moderator", "expert", "participant", "observer"]
+
+
+class PermissionContext(TypedDict, total=False):
+    role: Role
+    is_creator: 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: str, 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: str, 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:
+        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 in {ROOM_CREATE, ROOM_JOIN}:
+        return True
+    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_INVITE, ROOM_INVITE_REVOKE, 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_INVITE,
+        ROOM_INVITE_REVOKE,
+        ROOM_CLOSE,
+        MESSAGE_TEXT,
+        MESSAGE_MARKDOWN,
+        MESSAGE_DATA,
+        SOURCE_ADD,
+        TURN_UPDATE,
+        QUESTION_GENERATE,
+        DISCOURSE_STEER,
+        MINDMAP_UPDATE,
+        REPORT_GENERATE,
+        PROPOSAL_CREATE,
+        POLL_CREATE,
+        POLL_VOTE,
+        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_TEXT,
+        MESSAGE_MARKDOWN,
+        MESSAGE_DATA,
+        SOURCE_ADD,
+        DISCOURSE_STEER,
+        PROPOSAL_CREATE,
+        POLL_CREATE,
+        POLL_VOTE,
+        REACTION_CREATE,
+        ROOM_LEAVE,
+    }
+    policy_events = {QUESTION_GENERATE, MINDMAP_UPDATE, REPORT_GENERATE, 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 == DISCOURSE_STEER)
+        or (context.get("observer_poll_vote_allowed", False) and event_type == POLL_VOTE)
+    )

agent_protocols-0.1.0/src/agent_protocols/errors.py

@@ -0,0 +1,4 @@
+class AgentProtocolError(ValueError):
+    def __init__(self, code: str, message: str):
+        super().__init__(message)
+        self.code = code

agent_protocols-0.1.0/src/agent_protocols/http_client.py

@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+from typing import Any
+
+try:
+    import requests
+except ImportError:  # pragma: no cover
+    requests = None  # type: ignore[assignment]
+
+from .identity import AgentId, Envelope
+
+
+class ProfileClient:
+    def __init__(self, base_url: str, session: Any | None = None):
+        self.base_url = base_url.rstrip("/")
+        self.session = session or _requests_session()
+
+    def get_profile(self, agent_id: AgentId) -> dict[str, Any]:
+        return self._get(f"/v1/profiles/{agent_id}")
+
+    def submit_profile_update(self, envelope: Envelope) -> dict[str, Any]:
+        return self._post("/v1/profiles", envelope)
+
+    def _get(self, path: str) -> dict[str, Any]:
+        response = self.session.get(self.base_url + path)
+        response.raise_for_status()
+        return response.json()
+
+    def _post(self, path: str, body: Any) -> dict[str, Any]:
+        response = self.session.post(self.base_url + path, json=body)
+        response.raise_for_status()
+        return response.json()
+
+
+class DiscourseClient:
+    def __init__(self, base_url: str, session: Any | None = None):
+        self.base_url = base_url.rstrip("/")
+        self.session = session or _requests_session()
+
+    def protocol(self) -> dict[str, Any]:
+        return self._get("/v1/protocol")
+
+    def create_room(self, envelope: Envelope) -> dict[str, Any]:
+        return self._post("/v1/rooms", envelope)
+
+    def join_room(self, room_id: str, envelope: Envelope) -> dict[str, Any]:
+        return self._post(f"/v1/rooms/{room_id}/join", envelope)
+
+    def leave_room(self, room_id: str, envelope: Envelope) -> dict[str, Any]:
+        return self._post(f"/v1/rooms/{room_id}/leave", envelope)
+
+    def submit_event(self, room_id: str, envelope: Envelope) -> dict[str, Any]:
+        return self._post(f"/v1/rooms/{room_id}/events", envelope)
+
+    def events(self, room_id: str) -> list[dict[str, Any]]:
+        return self._get(f"/v1/rooms/{room_id}/events")
+
+    def archive(self, room_id: str) -> dict[str, Any]:
+        return self._get(f"/v1/rooms/{room_id}/archive")
+
+    def _get(self, path: str) -> Any:
+        response = self.session.get(self.base_url + path)
+        response.raise_for_status()
+        return response.json()
+
+    def _post(self, path: str, body: Any) -> Any:
+        response = self.session.post(self.base_url + path, json=body)
+        response.raise_for_status()
+        return response.json()
+
+
+def _requests_session() -> Any:
+    if requests is None:
+        raise RuntimeError("Install agent-protocols[http] to use HTTP clients")
+    return requests.Session()

agent_protocols-0.1.0/src/agent_protocols/identity.py

@@ -0,0 +1,274 @@
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+import os
+import time
+from dataclasses import dataclass
+from typing import Any, MutableMapping, Protocol
+
+import base58
+import rfc8785
+from cryptography.exceptions import InvalidSignature
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey, Ed25519PublicKey
+from cryptography.hazmat.primitives.serialization import Encoding, PublicFormat
+
+from .errors import AgentProtocolError
+
+AGENT_ID_PREFIX = "did:agent:"
+EVENT_ID_PREFIX = "evt_"
+DEFAULT_LIVE_WRITE_WINDOW_MS = 300_000
+DEFAULT_REQUEST_JWT_TTL_SECS = 300
+_REQUEST_AUTH_REPLAY_SCOPE = "agent-identity/request-auth"
+
+Event = dict[str, Any]
+Envelope = dict[str, Any]
+AgentId = str
+
+
+def agent_id_from_public_key(public_key: bytes) -> AgentId:
+    if len(public_key) != 32:
+        raise AgentProtocolError("invalid_public_key", f"public key must be 32 bytes, got {len(public_key)}")
+    return f"{AGENT_ID_PREFIX}{_base58btc_encode(public_key)}"
+
+
+def public_key_bytes(agent_id: AgentId) -> bytes:
+    if not agent_id.startswith(AGENT_ID_PREFIX):
+        raise AgentProtocolError("invalid_agent_id", "agent id must start with did:agent:")
+    data = _base58btc_decode(agent_id[len(AGENT_ID_PREFIX):])
+    if len(data) != 32:
+        raise AgentProtocolError("invalid_public_key", f"agent id public key must be 32 bytes, got {len(data)}")
+    return data
+
+
+def validate_agent_id(agent_id: AgentId) -> AgentId:
+    public_key_bytes(agent_id)
+    return agent_id
+
+
+@dataclass(frozen=True)
+class RequestBinding:
+    audience: str
+    method: str
+    host: str
+    path: str
+
+    @classmethod
+    def create(cls, audience: str, method: str, host: str, path: str) -> "RequestBinding":
+        return cls(audience=audience, method=method.upper(), host=host, path=path)
+
+
+class AgentSigner:
+    def __init__(self, private_key: Ed25519PrivateKey):
+        self._private_key = private_key
+
+    @classmethod
+    def generate(cls) -> "AgentSigner":
+        return cls(Ed25519PrivateKey.generate())
+
+    @classmethod
+    def from_seed(cls, seed: bytes) -> "AgentSigner":
+        if len(seed) != 32:
+            raise AgentProtocolError("invalid_private_key", f"seed must be 32 bytes, got {len(seed)}")
+        return cls(Ed25519PrivateKey.from_private_bytes(seed))
+
+    def public_key(self) -> bytes:
+        return self._private_key.public_key().public_bytes(Encoding.Raw, PublicFormat.Raw)
+
+    def agent_id(self) -> AgentId:
+        return agent_id_from_public_key(self.public_key())
+
+    def sign_event(self, event: Event) -> Envelope:
+        return {
+            "event_id": event_id(event),
+            "event": event,
+            "signature": sign_event(self._private_key, event),
+        }
+
+    def sign_request_jwt(self, claims: dict[str, Any]) -> str:
+        agent_id = self.agent_id()
+        if claims.get("iss") != agent_id or claims.get("sub") != agent_id:
+            raise AgentProtocolError("invalid_jwt_claim", "iss and sub must match the signing agent id")
+        header = {"alg": "EdDSA", "typ": "JWT", "kid": agent_id}
+        encoded_header = _base64url_encode(json.dumps(header, separators=(",", ":")).encode())
+        encoded_payload = _base64url_encode(json.dumps(claims, separators=(",", ":")).encode())
+        signing_input = f"{encoded_header}.{encoded_payload}".encode()
+        signature = self._private_key.sign(signing_input)
+        return f"{encoded_header}.{encoded_payload}.{_base64url_encode(signature)}"
+
+
+class NonceStore(Protocol):
+    def check_and_insert(self, scope: tuple[AgentId, str, str | None, str]) -> None: ...
+
+
+class MemoryNonceStore:
+    def __init__(self) -> None:
+        self._seen: set[tuple[AgentId, str, str | None, str]] = set()
+
+    def check_and_insert(self, scope: tuple[AgentId, str, str | None, str]) -> None:
+        if scope in self._seen:
+            raise AgentProtocolError("nonce_reused", "nonce was already used in this replay scope")
+        self._seen.add(scope)
+
+
+def create_event(protocol: str, event_type: str, actor: AgentId, created_at: int, nonce: str, payload: Any) -> Event:
+    validate_agent_id(actor)
+    return {
+        "protocol": protocol,
+        "type": event_type,
+        "actor": actor,
+        "created_at": created_at,
+        "nonce": nonce,
+        "payload": payload,
+    }
+
+
+def with_room_id(event: Event, room_id: str) -> Event:
+    next_event = dict(event)
+    next_event["room_id"] = room_id
+    return next_event
+
+
+def canonical_event_bytes(event: Event) -> bytes:
+    canonical = rfc8785.dumps(event)
+    return canonical if isinstance(canonical, bytes) else canonical.encode()
+
+
+def event_id(event: Event) -> str:
+    digest = hashlib.sha256(canonical_event_bytes(event)).digest()
+    return f"{EVENT_ID_PREFIX}{_base58btc_encode(digest)}"
+
+
+def sign_event(private_key: Ed25519PrivateKey, event: Event) -> str:
+    return _base64url_encode(private_key.sign(canonical_event_bytes(event)))
+
+
+def verify_event_id(envelope: Envelope) -> None:
+    expected = event_id(envelope["event"])
+    actual = envelope["event_id"]
+    if expected != actual:
+        raise AgentProtocolError("invalid_event_id", f"invalid event id: expected {expected}, got {actual}")
+
+
+def verify_signature(envelope: Envelope) -> None:
+    signature = _base64url_decode(envelope["signature"])
+    if len(signature) != 64:
+        raise AgentProtocolError("invalid_signature", f"signature must be 64 bytes, got {len(signature)}")
+    public_key = Ed25519PublicKey.from_public_bytes(public_key_bytes(envelope["event"]["actor"]))
+    try:
+        public_key.verify(signature, canonical_event_bytes(envelope["event"]))
+    except InvalidSignature as exc:
+        raise AgentProtocolError("invalid_signature", "signature verification failed") from exc
+
+
+def verify_envelope(envelope: Envelope) -> None:
+    verify_event_id(envelope)
+    verify_signature(envelope)
+
+
+def verify_timestamp(created_at: int, now_ms: int, window_ms: int) -> None:
+    if window_ms < 0 or abs(created_at - now_ms) > window_ms:
+        raise AgentProtocolError("timestamp_out_of_window", "timestamp is outside the allowed live-write window")
+
+
+def nonce_scope_for_event(event: Event, kind: str = "actor_protocol") -> tuple[AgentId, str, str | None, str]:
+    room_id = event.get("room_id") if kind == "actor_room" else None
+    return (event["actor"], event["protocol"], room_id, event["nonce"])
+
+
+def verify_live_envelope(envelope: Envelope, nonce_store: NonceStore, *, now_ms: int | None = None, window_ms: int = DEFAULT_LIVE_WRITE_WINDOW_MS, nonce_scope: str = "actor_protocol") -> None:
+    verify_envelope(envelope)
+    verify_timestamp(envelope["event"]["created_at"], now_ms if now_ms is not None else unix_time_millis(), window_ms)
+    nonce_store.check_and_insert(nonce_scope_for_event(envelope["event"], nonce_scope))
+
+
+def create_request_jwt_claims(agent_id: AgentId, binding: RequestBinding, issued_at: int, ttl_secs: int, jti: str) -> dict[str, Any]:
+    return {
+        "iss": agent_id,
+        "sub": agent_id,
+        "aud": binding.audience,
+        "iat": issued_at,
+        "exp": issued_at + ttl_secs,
+        "jti": jti,
+        "method": binding.method.upper(),
+        "host": binding.host,
+        "path": binding.path,
+    }
+
+
+def verify_request_jwt(token: str, *, audience: str, method: str, host: str, path: str, now_secs: int | None = None, max_ttl_secs: int = DEFAULT_REQUEST_JWT_TTL_SECS) -> dict[str, Any]:
+    parts = token.split(".")
+    if len(parts) != 3:
+        raise AgentProtocolError("invalid_jwt", "expected three compact JWS parts")
+    header = json.loads(_base64url_decode(parts[0]))
+    claims = json.loads(_base64url_decode(parts[1]))
+    signature = _base64url_decode(parts[2])
+    signing_input = f"{parts[0]}.{parts[1]}".encode()
+
+    if header.get("alg") != "EdDSA":
+        raise AgentProtocolError("invalid_jwt_claim", "alg must be EdDSA")
+    if header.get("typ") != "JWT":
+        raise AgentProtocolError("invalid_jwt_claim", "typ must be JWT")
+    if header.get("kid") != claims.get("iss") or claims.get("iss") != claims.get("sub"):
+        raise AgentProtocolError("invalid_jwt_claim", "kid, iss, and sub must identify the same Agent ID")
+
+    public_key = Ed25519PublicKey.from_public_bytes(public_key_bytes(header["kid"]))
+    try:
+        public_key.verify(signature, signing_input)
+    except InvalidSignature as exc:
+        raise AgentProtocolError("invalid_signature", "JWT signature verification failed") from exc
+
+    expected_method = method.upper()
+    if claims.get("aud") != audience:
+        raise AgentProtocolError("invalid_jwt_claim", "aud mismatch")
+    if claims.get("method") != expected_method:
+        raise AgentProtocolError("invalid_jwt_claim", "method mismatch")
+    if claims.get("host") != host:
+        raise AgentProtocolError("invalid_jwt_claim", "host mismatch")
+    if claims.get("path") != path:
+        raise AgentProtocolError("invalid_jwt_claim", "path mismatch")
+
+    now = now_secs if now_secs is not None else unix_time_secs()
+    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:
+        raise AgentProtocolError("invalid_jwt_claim", "JWT ttl exceeds maximum")
+    return claims
+
+
+def verify_request_jwt_live(token: str, nonce_store: NonceStore, **context: Any) -> dict[str, Any]:
+    claims = verify_request_jwt(token, **context)
+    nonce_store.check_and_insert((claims["iss"], _REQUEST_AUTH_REPLAY_SCOPE, None, claims["jti"]))
+    return claims
+
+
+def unix_time_millis() -> int:
+    return int(time.time() * 1000)
+
+
+def unix_time_secs() -> int:
+    return int(time.time())
+
+
+def random_nonce(prefix: str = "n_") -> str:
+    return f"{prefix}{_base64url_encode(os.urandom(16))}"
+
+
+def _base58btc_encode(data: bytes) -> str:
+    return "z" + base58.b58encode(data).decode()
+
+
+def _base58btc_decode(value: str) -> bytes:
+    if not value.startswith("z"):
+        raise AgentProtocolError("invalid_encoding", "expected base58btc multibase value")
+    return base58.b58decode(value[1:])
+
+
+def _base64url_encode(data: bytes) -> str:
+    return base64.urlsafe_b64encode(data).rstrip(b"=").decode()
+
+
+def _base64url_decode(value: str) -> bytes:
+    padding = "=" * ((4 - len(value) % 4) % 4)
+    return base64.urlsafe_b64decode(value + padding)

agent_protocols-0.1.0/src/agent_protocols/profile.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+from typing import Any
+
+from .errors import AgentProtocolError
+from .identity import AgentId, Envelope, Event, create_event, verify_envelope
+
+PROFILE_PROTOCOL = "agent-profile/1.0"
+PROFILE_UPDATE = "profile.update"
+
+ProfileUpdatePayload = dict[str, Any]
+AgentProfile = dict[str, Any]
+
+
+def profile_update_event(actor: AgentId, created_at: int, nonce: str, payload: ProfileUpdatePayload) -> Event:
+    return create_event(PROFILE_PROTOCOL, PROFILE_UPDATE, actor, created_at, nonce, payload)
+
+
+def validate_profile_update(envelope: Envelope) -> None:
+    verify_envelope(envelope)
+    event = envelope["event"]
+    if event["protocol"] != PROFILE_PROTOCOL:
+        raise AgentProtocolError("invalid_event_protocol", f"expected {PROFILE_PROTOCOL}, got {event['protocol']}")
+    if event["type"] != PROFILE_UPDATE:
+        raise AgentProtocolError("invalid_event_type", f"expected {PROFILE_UPDATE}, got {event['type']}")
+    if event["actor"] != event["payload"].get("agent_id"):
+        raise AgentProtocolError("invalid_actor", "profile update actor must match payload.agent_id")
+
+
+def materialize_profile(envelope: Envelope) -> AgentProfile:
+    validate_profile_update(envelope)
+    payload = envelope["event"]["payload"]
+    return {
+        "agent_id": payload["agent_id"],
+        "name": payload["name"],
+        "description": payload.get("description"),
+        "avatar_url": payload.get("avatar_url"),
+        "provider": payload.get("provider"),
+        "capabilities": payload.get("capabilities", []),
+        "service_endpoints": payload.get("service_endpoints", []),
+        "links": payload.get("links", {}),
+        "metadata": payload.get("metadata", {}),
+        "updated_at": envelope["event"]["created_at"],
+        "profile_event_id": envelope["event_id"],
+    }

agent_protocols-0.1.0/src/agent_protocols.egg-info/PKG-INFO

@@ -0,0 +1,41 @@
+Metadata-Version: 2.4
+Name: agent-protocols
+Version: 0.1.0
+Summary: Python SDK for Agent Identity, Agent Profile, and Agent Discourse protocols
+Author: LDCLabs
+License: MIT
+Keywords: agent,protocol,ed25519,sdk
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: base58<3,>=2.1
+Requires-Dist: cryptography>=42
+Requires-Dist: rfc8785<0.2,>=0.1.4
+Provides-Extra: http
+Requires-Dist: requests<3,>=2.31; extra == "http"
+
+# agent-protocols Python SDK
+
+Python SDK for the draft Agent Identity, Agent Profile, and Agent Discourse protocols.
+
+## Modules
+
+- `agent_protocols.identity`: `did:agent:` encoding, JCS canonicalization, event IDs, Ed25519 signing and verification, live-write nonce checks, request JWT helpers.
+- `agent_protocols.profile`: `profile.update` payload helpers, validation, materialization.
+- `agent_protocols.discourse`: ADP event constants, room helpers, room-path checks, permission and state helpers.
+- `agent_protocols.http_client`: optional requests-based Profile and Discourse clients. Install with `agent-protocols[http]`.
+
+## Example
+
+```python
+from agent_protocols import AgentSigner, materialize_profile, profile_update_event, unix_time_millis
+
+signer = AgentSigner.generate()
+event = profile_update_event(
+    signer.agent_id(),
+    unix_time_millis(),
+    "n_01J8Z6",
+    {"agent_id": signer.agent_id(), "name": "ResearchAgent-v3"},
+)
+envelope = signer.sign_event(event)
+profile = materialize_profile(envelope)
+```

agent_protocols-0.1.0/src/agent_protocols.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+README.md
+pyproject.toml
+src/agent_protocols/__init__.py
+src/agent_protocols/discourse.py
+src/agent_protocols/errors.py
+src/agent_protocols/http_client.py
+src/agent_protocols/identity.py
+src/agent_protocols/profile.py
+src/agent_protocols.egg-info/PKG-INFO
+src/agent_protocols.egg-info/SOURCES.txt
+src/agent_protocols.egg-info/dependency_links.txt
+src/agent_protocols.egg-info/requires.txt
+src/agent_protocols.egg-info/top_level.txt
+tests/test_discourse.py
+tests/test_identity.py
+tests/test_profile.py

agent_protocols-0.1.0/src/agent_protocols.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

agent_protocols-0.1.0/src/agent_protocols.egg-info/requires.txt

@@ -0,0 +1,6 @@
+base58<3,>=2.1
+cryptography>=42
+rfc8785<0.2,>=0.1.4
+
+[http]
+requests<3,>=2.31

agent_protocols-0.1.0/src/agent_protocols.egg-info/top_level.txt

@@ -0,0 +1 @@
+agent_protocols

agent_protocols-0.1.0/tests/test_discourse.py

@@ -0,0 +1,52 @@
+import unittest
+
+from agent_protocols.discourse import (
+    MESSAGE_TEXT,
+    REACTION_CREATE,
+    ROOM_CANCEL,
+    ROOM_CREATE,
+    can_accept_room_write,
+    can_submit_event,
+    room_create_event,
+    validate_discourse_envelope,
+)
+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,
+            "n_room",
+            {"topic": "Research room", "visibility": "public", "start_time": 1000, "end_time": 2000},
+        )
+        envelope = signer.sign_event(event)
+
+        validate_discourse_envelope(envelope)
+
+    def test_rejects_room_event_without_room_id(self):
+        signer = AgentSigner.from_seed(bytes([15]) * 32)
+        event = create_event("agent-discourse/1.0", MESSAGE_TEXT, signer.agent_id(), 100, "n_message", {"text": "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_TEXT, {"role": "observer"}))
+        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_TEXT, "active", {"role": "participant"}))
+        self.assertFalse(can_accept_room_write(MESSAGE_TEXT, "scheduled", {"role": "participant"}))
+        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))
+
+
+if __name__ == "__main__":
+    unittest.main()

agent_protocols-0.1.0/tests/test_identity.py

@@ -0,0 +1,86 @@
+import unittest
+
+from agent_protocols.identity import (
+    AgentSigner,
+    MemoryNonceStore,
+    RequestBinding,
+    create_event,
+    create_request_jwt_claims,
+    verify_envelope,
+    verify_live_envelope,
+    verify_request_jwt_live,
+)
+
+
+class IdentityTests(unittest.TestCase):
+    def test_signs_and_verifies_event_envelopes(self):
+        signer = AgentSigner.from_seed(bytes([7]) * 32)
+        event = create_event(
+            "agent-profile/1.0",
+            "profile.update",
+            signer.agent_id(),
+            1_779_753_600_000,
+            "n_test",
+            {"agent_id": signer.agent_id(), "name": "ResearchAgent"},
+        )
+
+        envelope = signer.sign_event(event)
+
+        self.assertTrue(envelope["event_id"].startswith("evt_z"))
+        verify_envelope(envelope)
+
+    def test_rejects_tampered_payloads(self):
+        signer = AgentSigner.from_seed(bytes([8]) * 32)
+        envelope = signer.sign_event(
+            create_event("agent-profile/1.0", "profile.update", signer.agent_id(), 1000, "n_test", {"name": "before"})
+        )
+        envelope["event"]["payload"] = {"name": "after"}
+
+        with self.assertRaises(Exception):
+            verify_envelope(envelope)
+
+    def test_rejects_nonce_reuse(self):
+        signer = AgentSigner.from_seed(bytes([9]) * 32)
+        envelope = signer.sign_event(
+            create_event("agent-profile/1.0", "profile.update", signer.agent_id(), 1000, "n_reused", {"name": "ResearchAgent"})
+        )
+        store = MemoryNonceStore()
+
+        verify_live_envelope(envelope, store, now_ms=1000, window_ms=1000)
+        with self.assertRaises(Exception):
+            verify_live_envelope(envelope, store, now_ms=1000, window_ms=1000)
+
+    def test_signs_and_verifies_request_jwts(self):
+        signer = AgentSigner.from_seed(bytes([10]) * 32)
+        binding = RequestBinding.create("https://api.example.com", "get", "api.example.com", "/v1/profiles/did:agent:test")
+        claims = create_request_jwt_claims(signer.agent_id(), binding, 100, 300, "jwt_nonce")
+        token = signer.sign_request_jwt(claims)
+        store = MemoryNonceStore()
+
+        verified = verify_request_jwt_live(
+            token,
+            store,
+            audience=binding.audience,
+            method=binding.method,
+            host=binding.host,
+            path=binding.path,
+            now_secs=120,
+            max_ttl_secs=300,
+        )
+
+        self.assertEqual(verified["jti"], "jwt_nonce")
+        with self.assertRaises(Exception):
+            verify_request_jwt_live(
+                token,
+                store,
+                audience=binding.audience,
+                method=binding.method,
+                host=binding.host,
+                path=binding.path,
+                now_secs=120,
+                max_ttl_secs=300,
+            )
+
+
+if __name__ == "__main__":
+    unittest.main()

agent_protocols-0.1.0/tests/test_profile.py

@@ -0,0 +1,30 @@
+import unittest
+
+from agent_protocols.identity import AgentSigner
+from agent_protocols.profile import materialize_profile, profile_update_event, validate_profile_update
+
+
+class ProfileTests(unittest.TestCase):
+    def test_materializes_valid_profile_update(self):
+        signer = AgentSigner.from_seed(bytes([11]) * 32)
+        payload = {"agent_id": signer.agent_id(), "name": "ResearchAgent-v3", "capabilities": ["research"]}
+        envelope = signer.sign_event(profile_update_event(signer.agent_id(), 1_779_753_600_000, "n_profile", payload))
+
+        profile = materialize_profile(envelope)
+
+        self.assertEqual(profile["name"], "ResearchAgent-v3")
+        self.assertEqual(profile["updated_at"], 1_779_753_600_000)
+        self.assertEqual(profile["profile_event_id"], envelope["event_id"])
+
+    def test_rejects_actor_payload_mismatch(self):
+        signer = AgentSigner.from_seed(bytes([12]) * 32)
+        other = AgentSigner.from_seed(bytes([13]) * 32)
+        payload = {"agent_id": other.agent_id(), "name": "Imposter"}
+        envelope = signer.sign_event(profile_update_event(signer.agent_id(), 1_779_753_600_000, "n_profile", payload))
+
+        with self.assertRaises(Exception):
+            validate_profile_update(envelope)
+
+
+if __name__ == "__main__":
+    unittest.main()