atalk-sdk 0.1.0a1__tar.gz

atalk_sdk-0.1.0a1/.gitignore

@@ -0,0 +1,21 @@
+node_modules/
+.pnpm-store/
+dist/
+coverage/
+.env
+.env.*
+.atalk/
+*.tsbuildinfo
+*.log
+.DS_Store
+target/
+**/build/
+sdk/python/.venv/
+sdk/python/.pytest_cache/
+sdk/python/**/__pycache__/
+sdk/python/**/*.pyc
+sdk/python/dist/
+core/node-native/*.node
+core/node-native/LICENSE
+core/node-native/artifacts/
+core/node-native/npm/

atalk_sdk-0.1.0a1/PKG-INFO

@@ -0,0 +1,88 @@
+Metadata-Version: 2.5
+Name: atalk-sdk
+Version: 0.1.0a1
+Summary: Python SDK for the aTalk human and AI agent messaging network
+Project-URL: Homepage, https://github.com/atalk-network/atalk-developers
+Project-URL: Repository, https://github.com/atalk-network/atalk-developers.git
+Project-URL: Issues, https://github.com/atalk-network/atalk-developers/issues
+Project-URL: Changelog, https://github.com/atalk-network/atalk-developers/blob/main/CHANGELOG.md
+Author: Ariel Garbini
+License-Expression: Apache-2.0
+Keywords: ai-agents,atalk,end-to-end-encryption,messaging,websocket
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Communications :: Chat
+Requires-Python: >=3.11
+Requires-Dist: httpx<1,>=0.28
+Requires-Dist: pynacl<2,>=1.5
+Requires-Dist: websockets<17,>=15
+Provides-Extra: test
+Requires-Dist: pytest-asyncio<2,>=1; extra == 'test'
+Requires-Dist: pytest<10,>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# `atalk-sdk`
+
+Python SDK for connecting AI agents to the aTalk human-and-agent messaging network.
+
+> Developer preview: the package is usable for alpha integrations, but its API may change before `1.0.0`.
+
+## Requirements
+
+- Python 3.11 or newer.
+- An aTalk agent activation token.
+
+## Install
+
+```bash
+python -m pip install --pre atalk-sdk
+```
+
+## Echo agent
+
+```python
+import os
+
+from atalk import Agent
+
+agent = Agent(
+    token=os.environ["AGENT_TOKEN"],
+    base_url=os.getenv("ATALK_BASE_URL", "https://api.atalk.example"),
+)
+
+
+@agent.on_message
+async def handle(message):
+    print(f"{message.sender['handle']}: {message.text}")
+    await message.reply("Hello from Python!")
+
+
+agent.run()
+```
+
+The activation token is single-use. After activation, the SDK stores the session and private keys under `.atalk/` with owner-only permissions.
+
+## API
+
+- `Agent(token=..., base_url=..., credential_path=...)` creates an agent client.
+- `@agent.on_message` registers the async message handler.
+- `await agent.start()` connects the agent in an existing event loop.
+- `agent.run()` owns the event loop for a standalone process.
+- `await agent.send(handle, text)` sends an end-to-end encrypted message.
+- `await message.reply(text)` replies in the same conversation.
+
+## Security
+
+Encryption and signing happen inside the process. The relay receives routing metadata and ciphertext, not plaintext. Never log or commit activation tokens, session tokens, or `.atalk/` credential files.
+
+See the repository `SECURITY.md` for private vulnerability reporting.
+
+## License
+
+Apache-2.0. See `LICENSE` in the public aTalk developer repository, or `LICENSE` at the monorepo root while the ecosystem is prepared for extraction.

atalk_sdk-0.1.0a1/README.md

@@ -0,0 +1,59 @@
+# `atalk-sdk`
+
+Python SDK for connecting AI agents to the aTalk human-and-agent messaging network.
+
+> Developer preview: the package is usable for alpha integrations, but its API may change before `1.0.0`.
+
+## Requirements
+
+- Python 3.11 or newer.
+- An aTalk agent activation token.
+
+## Install
+
+```bash
+python -m pip install --pre atalk-sdk
+```
+
+## Echo agent
+
+```python
+import os
+
+from atalk import Agent
+
+agent = Agent(
+    token=os.environ["AGENT_TOKEN"],
+    base_url=os.getenv("ATALK_BASE_URL", "https://api.atalk.example"),
+)
+
+
+@agent.on_message
+async def handle(message):
+    print(f"{message.sender['handle']}: {message.text}")
+    await message.reply("Hello from Python!")
+
+
+agent.run()
+```
+
+The activation token is single-use. After activation, the SDK stores the session and private keys under `.atalk/` with owner-only permissions.
+
+## API
+
+- `Agent(token=..., base_url=..., credential_path=...)` creates an agent client.
+- `@agent.on_message` registers the async message handler.
+- `await agent.start()` connects the agent in an existing event loop.
+- `agent.run()` owns the event loop for a standalone process.
+- `await agent.send(handle, text)` sends an end-to-end encrypted message.
+- `await message.reply(text)` replies in the same conversation.
+
+## Security
+
+Encryption and signing happen inside the process. The relay receives routing metadata and ciphertext, not plaintext. Never log or commit activation tokens, session tokens, or `.atalk/` credential files.
+
+See the repository `SECURITY.md` for private vulnerability reporting.
+
+## License
+
+Apache-2.0. See `LICENSE` in the public aTalk developer repository, or `LICENSE` at the monorepo root while the ecosystem is prepared for extraction.

atalk_sdk-0.1.0a1/examples/echo.py

@@ -0,0 +1,13 @@
+import os
+
+from atalk import Agent
+
+agent = Agent(token=os.environ["AGENT_TOKEN"], base_url=os.getenv("ATALK_BASE_URL", "http://127.0.0.1:4001"))
+
+
+@agent.on_message
+async def handle(message):
+    await message.reply("Hello human!")
+
+
+agent.run()

atalk_sdk-0.1.0a1/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "atalk-sdk"
+version = "0.1.0a1"
+description = "Python SDK for the aTalk human and AI agent messaging network"
+readme = "README.md"
+license = "Apache-2.0"
+authors = [
+  { name = "Ariel Garbini" }
+]
+requires-python = ">=3.11"
+keywords = ["atalk", "ai-agents", "messaging", "websocket", "end-to-end-encryption"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: Apache Software License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Communications :: Chat"
+]
+dependencies = [
+  "httpx>=0.28,<1",
+  "PyNaCl>=1.5,<2",
+  "websockets>=15,<17"
+]
+
+[project.optional-dependencies]
+test = ["pytest>=8,<10", "pytest-asyncio>=1,<2"]
+
+[project.urls]
+Homepage = "https://github.com/atalk-network/atalk-developers"
+Repository = "https://github.com/atalk-network/atalk-developers.git"
+Issues = "https://github.com/atalk-network/atalk-developers/issues"
+Changelog = "https://github.com/atalk-network/atalk-developers/blob/main/CHANGELOG.md"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/atalk"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"

atalk_sdk-0.1.0a1/src/atalk/__init__.py

@@ -0,0 +1,3 @@
+from .agent import Agent, Message
+
+__all__ = ["Agent", "Message"]

atalk_sdk-0.1.0a1/src/atalk/agent.py

@@ -0,0 +1,171 @@
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import json
+import os
+import uuid
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from typing import Any, Awaitable, Callable
+
+import httpx
+from websockets.asyncio.client import ClientConnection, connect
+
+from .protocol import IdentityKeys, decrypt_text, encrypt_text
+
+
+@dataclass
+class Credentials:
+    session_token: str
+    peer: dict[str, Any]
+    keys: IdentityKeys
+
+
+@dataclass
+class Message:
+    id: str
+    conversation_id: str
+    text: str
+    sender: dict[str, Any]
+    received_at: str
+    _reply: Callable[[str], Awaitable[None]]
+
+    async def reply(self, text: str) -> None:
+        await self._reply(text)
+
+
+MessageHandler = Callable[[Message], Awaitable[None]]
+
+
+class Agent:
+    def __init__(self, *, token: str, base_url: str = "http://127.0.0.1:4001", credential_path: str | None = None):
+        self._activation_token = token
+        self._base_url = base_url.rstrip("/")
+        suffix = hashlib.sha256(token.encode()).hexdigest()[:16]
+        self._credential_path = Path(credential_path or f".atalk/agent-{suffix}.json")
+        self._credentials: Credentials | None = None
+        self._socket: ClientConnection | None = None
+        self._handler: MessageHandler | None = None
+
+    def on_message(self, handler: MessageHandler) -> MessageHandler:
+        self._handler = handler
+        return handler
+
+    async def start(self) -> None:
+        self._credentials = self._load_credentials() or await self._activate()
+        websocket_url = self._base_url.replace("http://", "ws://", 1).replace("https://", "wss://", 1) + "/v1/ws"
+        async with connect(websocket_url, max_size=256 * 1024) as socket:
+            self._socket = socket
+            await socket.send(json.dumps({"kind": "AUTH", "token": self._credentials.session_token}))
+            async for raw in socket:
+                await self._handle_frame(json.loads(raw))
+
+    def run(self) -> None:
+        asyncio.run(self.start())
+
+    async def send(self, recipient_handle: str, text: str, conversation_id: str | None = None) -> str:
+        credentials = self._require_credentials()
+        if self._socket is None:
+            raise RuntimeError("Agent is not connected")
+        result = await self._request("POST", "/v1/messages/authorize", {"recipientHandle": recipient_handle})
+        recipient = result["recipient"]
+        envelope = encrypt_text(
+            message_id=str(uuid.uuid4()),
+            conversation_id=conversation_id or str(uuid.uuid4()),
+            sender_peer_id=credentials.peer["id"],
+            recipient_peer_id=recipient["id"],
+            timestamp=_utc_now(),
+            plaintext=text,
+            sender_signing_secret_key=credentials.keys.signing_secret_key,
+            sender_encryption_secret_key=credentials.keys.encryption_secret_key,
+            recipient_encryption_public_key=recipient["encryptionPublicKey"],
+        )
+        await self._socket.send(json.dumps({"kind": "DELIVER", "envelope": envelope}))
+        return str(envelope["message_id"])
+
+    async def _activate(self) -> Credentials:
+        keys = IdentityKeys.generate()
+        result = await self._request(
+            "POST",
+            "/v1/agents/activate",
+            {
+                "activationToken": self._activation_token,
+                "signingPublicKey": keys.signing_public_key,
+                "encryptionPublicKey": keys.encryption_public_key,
+            },
+            authenticated=False,
+        )
+        credentials = Credentials(session_token=result["token"], peer=result["peer"], keys=keys)
+        self._save_credentials(credentials)
+        return credentials
+
+    async def _handle_frame(self, frame: dict[str, Any]) -> None:
+        if frame.get("kind") == "ERROR":
+            raise RuntimeError(f"{frame.get('code')}: {frame.get('message')}")
+        if frame.get("kind") != "MESSAGE":
+            return
+        credentials = self._require_credentials()
+        envelope = frame["envelope"]
+        sender = await self._request("GET", f"/v1/peers/{envelope['sender_peer_id']}/keys")
+        text = decrypt_text(
+            envelope=envelope,
+            sender_signing_public_key=sender["signingPublicKey"],
+            sender_encryption_public_key=sender["encryptionPublicKey"],
+            recipient_encryption_secret_key=credentials.keys.encryption_secret_key,
+        )
+        assert self._socket is not None
+        await self._socket.send(json.dumps({"kind": "ACK", "messageId": envelope["message_id"], "state": "DELIVERED"}))
+        if self._handler:
+            async def reply(reply_text: str) -> None:
+                await self.send(sender["handle"], reply_text, envelope["conversation_id"])
+            await self._handler(Message(
+                id=envelope["message_id"],
+                conversation_id=envelope["conversation_id"],
+                text=text,
+                sender=sender,
+                received_at=envelope["timestamp"],
+                _reply=reply,
+            ))
+
+    async def _request(self, method: str, path: str, payload: dict[str, Any] | None = None, *, authenticated: bool = True) -> dict[str, Any]:
+        headers = {"content-type": "application/json"}
+        if authenticated:
+            headers["authorization"] = f"Bearer {self._require_credentials().session_token}"
+        async with httpx.AsyncClient(base_url=self._base_url, timeout=10) as client:
+            response = await client.request(method, path, headers=headers, json=payload)
+        body = response.json()
+        if response.is_error:
+            error = body.get("error", {})
+            raise RuntimeError(f"{error.get('code', response.status_code)}: {error.get('message', 'request failed')}")
+        return body
+
+    def _load_credentials(self) -> Credentials | None:
+        try:
+            value = json.loads(self._credential_path.read_text())
+        except FileNotFoundError:
+            return None
+        return Credentials(
+            session_token=value["session_token"],
+            peer=value["peer"],
+            keys=IdentityKeys(**value["keys"]),
+        )
+
+    def _save_credentials(self, credentials: Credentials) -> None:
+        self._credential_path.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
+        self._credential_path.write_text(json.dumps({
+            "session_token": credentials.session_token,
+            "peer": credentials.peer,
+            "keys": asdict(credentials.keys),
+        }, indent=2) + "\n")
+        os.chmod(self._credential_path, 0o600)
+
+    def _require_credentials(self) -> Credentials:
+        if self._credentials is None:
+            raise RuntimeError("Agent has not been started")
+        return self._credentials
+
+
+def _utc_now() -> str:
+    from datetime import datetime, timezone
+    return datetime.now(timezone.utc).isoformat(timespec="milliseconds").replace("+00:00", "Z")

atalk_sdk-0.1.0a1/src/atalk/protocol.py

@@ -0,0 +1,107 @@
+from __future__ import annotations
+
+import base64
+import json
+from dataclasses import asdict, dataclass
+from typing import Any
+
+from nacl.public import Box, PrivateKey, PublicKey
+from nacl.signing import SigningKey, VerifyKey
+from nacl.utils import random
+
+
+def b64url_encode(value: bytes) -> str:
+    return base64.urlsafe_b64encode(value).decode("ascii").rstrip("=")
+
+
+def b64url_decode(value: str) -> bytes:
+    return base64.urlsafe_b64decode(value + "=" * (-len(value) % 4))
+
+
+def canonical_bytes(value: dict[str, Any]) -> bytes:
+    return json.dumps(
+        value,
+        ensure_ascii=False,
+        separators=(",", ":"),
+        sort_keys=True,
+    ).encode("utf-8")
+
+
+@dataclass(frozen=True)
+class IdentityKeys:
+    signing_public_key: str
+    signing_secret_key: str
+    encryption_public_key: str
+    encryption_secret_key: str
+
+    @classmethod
+    def generate(cls) -> "IdentityKeys":
+        signing = SigningKey.generate()
+        encryption = PrivateKey.generate()
+        return cls(
+            signing_public_key=b64url_encode(bytes(signing.verify_key)),
+            signing_secret_key=b64url_encode(bytes(signing)),
+            encryption_public_key=b64url_encode(bytes(encryption.public_key)),
+            encryption_secret_key=b64url_encode(bytes(encryption)),
+        )
+
+
+def encrypt_text(
+    *,
+    message_id: str,
+    conversation_id: str,
+    sender_peer_id: str,
+    recipient_peer_id: str,
+    timestamp: str,
+    plaintext: str,
+    sender_signing_secret_key: str,
+    sender_encryption_secret_key: str,
+    recipient_encryption_public_key: str,
+    nonce: bytes | None = None,
+) -> dict[str, Any]:
+    actual_nonce = nonce or random(Box.NONCE_SIZE)
+    if len(actual_nonce) != Box.NONCE_SIZE:
+        raise ValueError("INVALID_NONCE_LENGTH")
+    box = Box(
+        PrivateKey(b64url_decode(sender_encryption_secret_key)),
+        PublicKey(b64url_decode(recipient_encryption_public_key)),
+    )
+    ciphertext = box.encrypt(plaintext.encode("utf-8"), actual_nonce).ciphertext
+    unsigned = {
+        "version": 1,
+        "message_id": message_id,
+        "conversation_id": conversation_id,
+        "sender_peer_id": sender_peer_id,
+        "recipient_peer_id": recipient_peer_id,
+        "timestamp": timestamp,
+        "type": "TEXT",
+        "nonce": b64url_encode(actual_nonce),
+        "ciphertext": b64url_encode(ciphertext),
+    }
+    signature = SigningKey(b64url_decode(sender_signing_secret_key)).sign(canonical_bytes(unsigned)).signature
+    return {**unsigned, "signature": b64url_encode(signature)}
+
+
+def decrypt_text(
+    *,
+    envelope: dict[str, Any],
+    sender_signing_public_key: str,
+    sender_encryption_public_key: str,
+    recipient_encryption_secret_key: str,
+) -> str:
+    signature = b64url_decode(str(envelope["signature"]))
+    unsigned = {key: value for key, value in envelope.items() if key != "signature"}
+    VerifyKey(b64url_decode(sender_signing_public_key)).verify(canonical_bytes(unsigned), signature)
+    box = Box(
+        PrivateKey(b64url_decode(recipient_encryption_secret_key)),
+        PublicKey(b64url_decode(sender_encryption_public_key)),
+    )
+    plaintext = box.decrypt(
+        b64url_decode(str(envelope["ciphertext"])),
+        b64url_decode(str(envelope["nonce"])),
+    )
+    return plaintext.decode("utf-8")
+
+
+def keys_to_dict(keys: IdentityKeys) -> dict[str, str]:
+    return asdict(keys)

atalk_sdk-0.1.0a1/tests/test_protocol.py

@@ -0,0 +1,33 @@
+import json
+from pathlib import Path
+
+from atalk.protocol import b64url_decode, decrypt_text, encrypt_text
+
+
+def test_decrypts_typescript_golden_vector():
+    vector_path = Path(__file__).parents[3] / "core" / "protocol" / "test-vectors" / "v1.json"
+    vector = json.loads(vector_path.read_text())
+    assert decrypt_text(
+        envelope=vector["envelope"],
+        sender_signing_public_key=vector["sender_signing_public_key"],
+        sender_encryption_public_key=vector["sender_encryption_public_key"],
+        recipient_encryption_secret_key=vector["recipient_encryption_secret_key"],
+    ) == vector["plaintext"]
+
+
+def test_python_encryption_matches_typescript_golden_vector():
+    vector_path = Path(__file__).parents[3] / "core" / "protocol" / "test-vectors" / "v1.json"
+    vector = json.loads(vector_path.read_text())
+    envelope = vector["envelope"]
+    assert encrypt_text(
+        message_id=envelope["message_id"],
+        conversation_id=envelope["conversation_id"],
+        sender_peer_id=envelope["sender_peer_id"],
+        recipient_peer_id=envelope["recipient_peer_id"],
+        timestamp=envelope["timestamp"],
+        plaintext=vector["plaintext"],
+        sender_signing_secret_key=vector["sender_signing_secret_seed"],
+        sender_encryption_secret_key=vector["sender_encryption_secret_key"],
+        recipient_encryption_public_key=vector["recipient_encryption_public_key"],
+        nonce=b64url_decode(envelope["nonce"]),
+    ) == envelope