chatxdk 0.2.0

X Chat SDK - End-to-end encryption for X Direct Messages (Python bindings)

chat-xdk Python bindings

Python bindings for the X Chat SDK — end-to-end encryption for X Direct Messages.

Install

pip install chatxdk

The PyPI distribution is chatxdk; import it as chat_xdk.

Architecture

Python (chat_xdk) → PyO3 → chat-xdk-core (Rust)

Prerequisites

• Python 3.10+
• Rust (stable) and maturin

Setup

From source (editable install):

cd crates/pyo3
pip install maturin
maturin develop

Release wheel:

maturin build --release
pip install target/wheels/*.whl

Quick Start

from chat_xdk import Chat

chat = Chat(config_json)
chat.unlock("2580")

# Initial load — batch decrypt with automatic key extraction.
# Each signing-key entry must include the identity public key and its binding
# signature so the SDK can verify the signing key is authentic.
result = chat.decrypt_events(raw_events, [
    {
        "user_id": "111",
        "public_key_version": "v1",
        "public_key": "BASE64...",
        "identity_public_key": "BASE64...",
        "identity_public_key_signature": "BASE64...",
    },
    {
        "user_id": "222",
        "public_key_version": "v1",
        "public_key": "BASE64...",
        "identity_public_key": "BASE64...",
        "identity_public_key_signature": "BASE64...",
    },
])

for dm in result["messages"]:
    if dm["event"]["type"] == "Message":
        print(dm["event"]["sender_id"], dm["event"]["content"]["text"])

# Cache keys, then use decrypt_event for individual events
cached_keys = result["conversation_keys"]["keys"]
event = chat.decrypt_event(new_event_b64, cached_keys, sender_signing_keys)

API

See the Python column of the unified tables in docs/API.md for the full method list, parameters, and return types.

Security limitations

The underlying protocol provides no forward secrecy and no post-compromise security: compromise of an identity private key exposes all conversation keys ever encrypted to that public key — and therefore all past and future messages in those conversations. Key rotation does not retroactively protect messages encrypted under a previous key. See docs/CRYPTO.md — Known Limitations.

License

MIT