buzzkit 0.1.0__tar.gz → 0.1.2__tar.gz

{buzzkit-0.1.0 → buzzkit-0.1.2}/.gitignore

@@ -6,3 +6,5 @@ __pycache__/
 *.egg-info/
 .python-version
 agent.secret
+/dist
+owner.secret

{buzzkit-0.1.0 → buzzkit-0.1.2}/Cargo.lock

@@ -168,7 +168,7 @@ dependencies = [
 
 [[package]]
 name = "buzzkit"
-version = "0.1.0"
+version = "0.1.2"
 dependencies = [
  "base64",
  "buzz-core",

{buzzkit-0.1.0 → buzzkit-0.1.2}/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "buzzkit"
-version = "0.1.0"
+version = "0.1.2"
 edition = "2021"
 publish = false
 description = "PyO3 bindings over Block's Buzz zero-I/O crates (buzz-core / buzz-sdk)"

{buzzkit-0.1.0 → buzzkit-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: buzzkit
-Version: 0.1.0
+Version: 0.1.2
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License

{buzzkit-0.1.0 → buzzkit-0.1.2}/examples/claim_invite.py

@@ -1,6 +1,6 @@
 """Redeem a relay invite so the agent becomes a community member.
 
-    BUZZ_RELAY_URL=wss://... python examples/claim_invite.py <invite_url_or_code>
+BUZZ_RELAY_URL=wss://... python examples/claim_invite.py <invite_url_or_code>
 """
 
 from __future__ import annotations

{buzzkit-0.1.0 → buzzkit-0.1.2}/examples/list_channels.py

@@ -1,6 +1,6 @@
 """List channels (kind 39000 metadata) visible to the agent.
 
-    BUZZ_RELAY_URL=wss://... python examples/list_channels.py
+BUZZ_RELAY_URL=wss://... python examples/list_channels.py
 """
 
 from __future__ import annotations

{buzzkit-0.1.0 → buzzkit-0.1.2}/examples/offline_sign.py

@@ -1,6 +1,6 @@
 """Offline proof — no relay. keygen -> sign a Buzz message -> verify -> tamper check.
 
-    python examples/offline_sign.py
+python examples/offline_sign.py
 """
 
 from __future__ import annotations

{buzzkit-0.1.0 → buzzkit-0.1.2}/examples/send_message.py

@@ -1,6 +1,6 @@
 """Post a message to a channel via the HTTP bridge.
 
-    BUZZ_RELAY_URL=wss://... python examples/send_message.py <channel-uuid> ["message"]
+BUZZ_RELAY_URL=wss://... python examples/send_message.py <channel-uuid> ["message"]
 """
 
 from __future__ import annotations

{buzzkit-0.1.0 → buzzkit-0.1.2}/examples/set_profile.py

@@ -1,6 +1,6 @@
 """Publish the agent's profile (kind 0) so it shows a display name in Buzz.
 
-    BUZZ_RELAY_URL=wss://... python examples/set_profile.py ["Display Name"]
+BUZZ_RELAY_URL=wss://... python examples/set_profile.py ["Display Name"]
 """
 
 from __future__ import annotations

{buzzkit-0.1.0 → buzzkit-0.1.2}/examples/subscribe.py

@@ -1,6 +1,6 @@
 """Real-time inbound: subscribe to a channel over the WebSocket and print messages.
 
-    BUZZ_RELAY_URL=wss://... python examples/subscribe.py <channel-uuid>
+BUZZ_RELAY_URL=wss://... python examples/subscribe.py <channel-uuid>
 """
 
 from __future__ import annotations

{buzzkit-0.1.0 → buzzkit-0.1.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "maturin"
 
 [project]
 name = "buzzkit"
-version = "0.1.0"
+version = "0.1.2"
 description = "Python bindings + async client for Block's Buzz (Nostr) protocol, backed by Rust buzz-core/buzz-sdk"
 readme = "README.md"
 requires-python = ">=3.12"

{buzzkit-0.1.0 → buzzkit-0.1.2}/python/buzzkit/__init__.py

@@ -10,6 +10,7 @@ This is an independent, unofficial project — not affiliated with Block, Inc.
 from __future__ import annotations
 
 from ._native import (
+    KIND_ADD_MEMBER,
     KIND_AUTH,
     KIND_HTTP_AUTH,
     KIND_PRESENCE_UPDATE,
@@ -17,8 +18,11 @@ from ._native import (
     KIND_STREAM_MESSAGE,
     KIND_STREAM_MESSAGE_V2,
     build_auth_event,
+    build_join_channel_event,
     build_message_event,
+    build_presence_event,
     build_profile_event,
+    compute_auth_tag,
     generate_keypair,
     pubkey_from_secret,
     sign_nip98,
@@ -26,9 +30,10 @@ from ._native import (
 )
 from .client import BuzzClient
 
-__version__ = "0.1.0"
+__version__ = "0.1.2"
 
 __all__ = [
+    "KIND_ADD_MEMBER",
     "KIND_AUTH",
     "KIND_HTTP_AUTH",
     "KIND_PRESENCE_UPDATE",
@@ -37,8 +42,11 @@ __all__ = [
     "KIND_STREAM_MESSAGE_V2",
     "BuzzClient",
     "build_auth_event",
+    "build_join_channel_event",
     "build_message_event",
+    "build_presence_event",
     "build_profile_event",
+    "compute_auth_tag",
     "generate_keypair",
     "pubkey_from_secret",
     "sign_nip98",

{buzzkit-0.1.0 → buzzkit-0.1.2}/python/buzzkit/_native.pyi

@@ -21,9 +21,20 @@ def build_profile_event(
 ) -> str:
     """Build + sign a profile event (kind 0); returns NIP-01 event JSON."""
 
-def build_auth_event(secret: str, challenge: str, relay_url: str) -> str:
+def build_join_channel_event(secret: str, channel_id: str) -> str:
+    """Build + sign a NIP-29 channel self-join event (kind 9000, role=bot)."""
+
+def build_presence_event(secret: str, status: str = ...) -> str:
+    """Build + sign a presence event (kind 20001); status online/away/offline."""
+
+def build_auth_event(
+    secret: str, challenge: str, relay_url: str, auth_tag: str | None = ...
+) -> str:
     """Build + sign a NIP-42 AUTH event (kind 22242); returns event JSON."""
 
+def compute_auth_tag(owner_secret: str, agent_pubkey_hex: str, conditions: str = ...) -> str:
+    """Compute a NIP-OA owner-attestation tag JSON attesting an agent pubkey."""
+
 def sign_nip98(secret: str, method: str, url: str, body: bytes | None = ...) -> str:
     """Return an ``Authorization: Nostr <base64>`` header value (NIP-98)."""
 
@@ -36,3 +47,4 @@ KIND_PRESENCE_UPDATE: int
 KIND_AUTH: int
 KIND_HTTP_AUTH: int
 KIND_STREAM_MESSAGE_V2: int
+KIND_ADD_MEMBER: int

{buzzkit-0.1.0 → buzzkit-0.1.2}/python/buzzkit/client.py

@@ -108,6 +108,22 @@ class BuzzClient:
         )
         return await self.post_event(ev)
 
+    async def join_channel(self, channel_id: str) -> dict:
+        """Self-add as a bot member of a channel (NIP-29 kind 9000).
+
+        Published over the WebSocket — NIP-29 management events are not accepted
+        on the HTTP bridge — so :meth:`connect` must be called first. Required
+        for the identity's messages to reach other channel members and for it to
+        appear in mention autocomplete.
+        """
+        ev = _native.build_join_channel_event(self._secret, channel_id)
+        return await self.publish(ev)
+
+    async def publish_presence(self, status: str = "online") -> dict:
+        """Announce presence (kind 20001, ephemeral) over the WebSocket."""
+        ev = _native.build_presence_event(self._secret, status)
+        return await self.publish(ev)
+
     async def query(self, filters: list[dict]) -> list[dict]:
         """Run a NIP-01 REQ over the HTTP bridge; returns a list of events."""
         url = f"{self._http}/query"
@@ -214,7 +230,9 @@ class BuzzClient:
                 q.put_nowait(("closed", "connection lost"))
 
     async def _on_auth_challenge(self, challenge: str) -> None:
-        auth_ev = json.loads(_native.build_auth_event(self._secret, challenge, self._ws_url))
+        auth_ev = json.loads(
+            _native.build_auth_event(self._secret, challenge, self._ws_url, self._auth_tag)
+        )
         self._auth_event_id = auth_ev["id"]
         await self._ws.send(json.dumps(["AUTH", auth_ev]))
 

{buzzkit-0.1.0 → buzzkit-0.1.2}/src/lib.rs

@@ -7,7 +7,7 @@
 
 use base64::engine::general_purpose::STANDARD as B64;
 use base64::Engine as _;
-use nostr::{EventBuilder, JsonUtil, Keys, Kind, RelayUrl, Tag, ToBech32};
+use nostr::{EventBuilder, JsonUtil, Keys, Kind, PublicKey, RelayUrl, Tag, ToBech32};
 use pyo3::exceptions::PyValueError;
 use pyo3::prelude::*;
 use sha2::{Digest, Sha256};
@@ -69,17 +69,50 @@ fn build_message_event(
 
 /// Build and sign a NIP-42 AUTH event (kind 22242) for a relay challenge.
 /// Returns the event JSON to send back as `["AUTH", <event>]`.
+///
+/// `auth_tag` is an optional NIP-OA owner-attestation tag JSON
+/// (`["auth", <owner>, <conditions>, <sig>]`) — inject it so the relay records
+/// the agent's owner.
 #[pyfunction]
-fn build_auth_event(secret: &str, challenge: &str, relay_url: &str) -> PyResult<String> {
+#[pyo3(signature = (secret, challenge, relay_url, auth_tag=None))]
+fn build_auth_event(
+    secret: &str,
+    challenge: &str,
+    relay_url: &str,
+    auth_tag: Option<&str>,
+) -> PyResult<String> {
     let keys = keys_from_secret(secret)?;
     let url = RelayUrl::parse(relay_url)
         .map_err(|e| PyValueError::new_err(format!("invalid relay url: {e}")))?;
-    let event = EventBuilder::auth(challenge, url)
+    let mut builder = EventBuilder::auth(challenge, url);
+    if let Some(tag_json) = auth_tag {
+        let tag = buzz_sdk::nip_oa::parse_auth_tag(tag_json)
+            .map_err(|e| PyValueError::new_err(format!("invalid auth_tag: {e}")))?;
+        builder = builder.tags([tag]);
+    }
+    let event = builder
         .sign_with_keys(&keys)
         .map_err(|e| PyValueError::new_err(format!("sign: {e}")))?;
     Ok(event.as_json())
 }
 
+/// Compute a NIP-OA owner-attestation tag: the OWNER signs an attestation over
+/// the agent's pubkey. Returns the `["auth", <owner>, <conditions>, <sig>]` tag
+/// JSON. `owner_secret` must differ from the agent (no self-attestation).
+#[pyfunction]
+#[pyo3(signature = (owner_secret, agent_pubkey_hex, conditions=""))]
+fn compute_auth_tag(
+    owner_secret: &str,
+    agent_pubkey_hex: &str,
+    conditions: &str,
+) -> PyResult<String> {
+    let owner_keys = keys_from_secret(owner_secret)?;
+    let agent_pubkey = PublicKey::from_hex(agent_pubkey_hex)
+        .map_err(|e| PyValueError::new_err(format!("invalid agent pubkey: {e}")))?;
+    buzz_sdk::nip_oa::compute_auth_tag(&owner_keys, &agent_pubkey, conditions)
+        .map_err(|e| PyValueError::new_err(format!("compute_auth_tag: {e}")))
+}
+
 /// Sign a NIP-98 HTTP-auth event (kind 27235). Returns the
 /// `Authorization: Nostr <base64>` header value for the Buzz HTTP bridge.
 #[pyfunction]
@@ -140,15 +173,51 @@ fn build_profile_event(
     Ok(event.as_json())
 }
 
+/// Build and sign a NIP-29 channel self-join event (kind 9000, role=bot).
+/// The signer adds itself (`p` = own pubkey) to `channel_id`'s member list.
+#[pyfunction]
+fn build_join_channel_event(secret: &str, channel_id: &str) -> PyResult<String> {
+    let keys = keys_from_secret(secret)?;
+    let cid = Uuid::parse_str(channel_id)
+        .map_err(|e| PyValueError::new_err(format!("channel_id must be a UUID: {e}")))?;
+    let pubkey_hex = keys.public_key().to_hex();
+    // The `p` tag references the signer itself (self-join), so we must opt into
+    // self-tagging — nostr's EventBuilder strips author-matching `p` tags by
+    // default, which the relay would then reject as "missing p tag".
+    let builder = buzz_sdk::build_add_member(cid, &pubkey_hex, Some(buzz_sdk::MemberRole::Bot))
+        .map_err(|e| PyValueError::new_err(format!("build_add_member: {e}")))?
+        .allow_self_tagging();
+    let event = builder
+        .sign_with_keys(&keys)
+        .map_err(|e| PyValueError::new_err(format!("sign: {e}")))?;
+    Ok(event.as_json())
+}
+
+/// Build and sign a presence event (kind 20001). `status` is "online",
+/// "away", or "offline". Ephemeral — publish over the WebSocket.
+#[pyfunction]
+#[pyo3(signature = (secret, status="online"))]
+fn build_presence_event(secret: &str, status: &str) -> PyResult<String> {
+    let keys = keys_from_secret(secret)?;
+    let event = buzz_sdk::build_presence_update(status)
+        .map_err(|e| PyValueError::new_err(format!("build_presence: {e}")))?
+        .sign_with_keys(&keys)
+        .map_err(|e| PyValueError::new_err(format!("sign: {e}")))?;
+    Ok(event.as_json())
+}
+
 #[pymodule]
 fn _native(m: &Bound<'_, PyModule>) -> PyResult<()> {
     m.add_function(wrap_pyfunction!(generate_keypair, m)?)?;
     m.add_function(wrap_pyfunction!(pubkey_from_secret, m)?)?;
     m.add_function(wrap_pyfunction!(build_message_event, m)?)?;
     m.add_function(wrap_pyfunction!(build_auth_event, m)?)?;
+    m.add_function(wrap_pyfunction!(compute_auth_tag, m)?)?;
     m.add_function(wrap_pyfunction!(sign_nip98, m)?)?;
     m.add_function(wrap_pyfunction!(verify_event, m)?)?;
     m.add_function(wrap_pyfunction!(build_profile_event, m)?)?;
+    m.add_function(wrap_pyfunction!(build_join_channel_event, m)?)?;
+    m.add_function(wrap_pyfunction!(build_presence_event, m)?)?;
 
     // Buzz event kinds (subset — mirrors buzz-core/src/kind.rs).
     m.add("KIND_REACTION", 7u16)?;
@@ -157,5 +226,6 @@ fn _native(m: &Bound<'_, PyModule>) -> PyResult<()> {
     m.add("KIND_AUTH", 22242u16)?;
     m.add("KIND_HTTP_AUTH", 27235u16)?;
     m.add("KIND_STREAM_MESSAGE_V2", 40002u16)?;
+    m.add("KIND_ADD_MEMBER", 9000u16)?;
     Ok(())
 }

{buzzkit-0.1.0 → buzzkit-0.1.2}/tests/test_signing.py

@@ -59,8 +59,39 @@ def test_nip98_header_shape():
 
 def test_auth_event_is_kind_22242():
     nsec, _, _ = buzzkit.generate_keypair()
-    event = json.loads(
-        buzzkit.build_auth_event(nsec, "challenge-123", "wss://relay.example")
-    )
+    event = json.loads(buzzkit.build_auth_event(nsec, "challenge-123", "wss://relay.example"))
     assert event["kind"] == buzzkit.KIND_AUTH == 22242
     assert ["challenge", "challenge-123"] in event["tags"]
+
+
+def test_join_channel_event_keeps_self_p_tag():
+    nsec, _, pk_hex = buzzkit.generate_keypair()
+    event = json.loads(buzzkit.build_join_channel_event(nsec, str(uuid.uuid4())))
+    assert event["kind"] == buzzkit.KIND_ADD_MEMBER == 9000
+    # The `p` tag references the signer itself; it must survive nostr's self-tag
+    # stripping (allow_self_tagging) or the relay rejects the join as "missing p tag".
+    assert ["p", pk_hex] in event["tags"]
+    assert ["role", "bot"] in event["tags"]
+    assert any(t[0] == "h" for t in event["tags"])
+
+
+def test_compute_auth_tag():
+    owner_nsec, _, owner_pk = buzzkit.generate_keypair()
+    _, _, agent_pk = buzzkit.generate_keypair()
+    tag = json.loads(buzzkit.compute_auth_tag(owner_nsec, agent_pk))
+    assert tag[0] == "auth"
+    assert tag[1] == owner_pk  # owner pubkey
+    assert len(tag) == 4  # ["auth", owner, conditions, sig]
+
+
+def test_compute_auth_tag_rejects_self():
+    nsec, _, pk_hex = buzzkit.generate_keypair()
+    with pytest.raises(ValueError):
+        buzzkit.compute_auth_tag(nsec, pk_hex)  # owner == agent
+
+
+def test_presence_event():
+    nsec, _, _ = buzzkit.generate_keypair()
+    event = json.loads(buzzkit.build_presence_event(nsec, "online"))
+    assert event["kind"] == buzzkit.KIND_PRESENCE_UPDATE == 20001
+    assert event["content"] == "online" or ["status", "online"] in event["tags"]