gbp-stack 1.2.3__tar.gz → 1.4.0__tar.gz

{gbp_stack-1.2.3 → gbp_stack-1.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gbp-stack
-Version: 1.2.3
+Version: 1.4.0
 Summary: Python bindings for the Group Protocol Stack: a layered, end-to-end encrypted group-messaging protocol family built on top of MLS (RFC 9420).
 Author: Group Protocol Stack contributors
 License: Apache-2.0
@@ -61,11 +61,23 @@ Beyond the protocol clients, the package ships ready-made helpers:
 * `SFrameSession` + `SFrameEncryptor` — SFrame (draft-ietf-sframe-enc) E2EE
   for GAP audio frames; per-sender AES-GCM keys derived from MLS exporter,
   1024-entry sliding-window replay protection.
+* `encode_gbp_frame` — low-level helper to construct a raw CBOR GBP frame.
+* `lookup_error` — return the CBOR `ErrorObject` for a known error code.
+
+### Coordinator events
+
+`NodeEvent` surfaces three new event kinds for coordinator election:
+
+| `kind` | Extra fields | Meaning |
+|--------|-------------|---------|
+| `coordinator_election_needed` | — | The local node should initiate GSP `COORDINATOR_CLAIM` |
+| `became_coordinator` | — | This node won the election |
+| `coordinator_claim` | `claimant` | A peer sent `COORDINATOR_CLAIM` with this member id |
 
 ## Install
 
 ```sh
-pip install gbp-stack==1.2.3
+pip install gbp-stack==1.4.0
 ```
 
 ## Quick start
@@ -77,7 +89,7 @@ with MlsContext.create("alice") as alice_mls, \
      MlsContext.create("bob")   as bob_mls:
 
     bob_kp  = bob_mls.export_key_package()
-    welcome = alice_mls.invite(bob_kp)
+    welcome = alice_mls.invite(bob_kp)       # alice auto-finalizes; epoch advances to 1
     bob_mls.accept_welcome(welcome)
 
     group_id = alice_mls.group_id
@@ -92,8 +104,67 @@ with MlsContext.create("alice") as alice_mls, \
         frame = gtp_alice.send(alice, alice_mls, target=2,
                                 message_id=0xCAFE_F00D, text="hello")
         for ev in bob.on_wire(bob_mls, frame.wire):
-            if ev.kind == "payload_received" and ev.stream_type == 2:
-                print(gtp_bob.accept(ev.plaintext).text)
+            if ev.kind == "payload_received" and ev.stream_type == 2:  # StreamType.Text
+                result = gtp_bob.accept(ev.plaintext, bob_mls.epoch)
+                print(result.text)   # → "hello"
+                # result.status is "new" (first message from this sender)
+                # subsequent messages → "new"; duplicates → "duplicate"
+```
+
+## GSP signals with per-signal arguments
+
+Signals that target a specific member or resource require CBOR-encoded `args`.
+The `send` method accepts an optional `args: bytes` keyword argument.
+
+```python
+import struct
+from gbp_stack import GspClient, SignalType
+
+# Minimal CBOR helpers
+def cbor_uint(n: int) -> bytes:
+    if n <= 23:     return bytes([n])
+    if n <= 0xFF:   return bytes([0x18, n])
+    if n <= 0xFFFF: return bytes([0x19, n >> 8, n & 0xFF])
+    return bytes([0x1A, (n>>24)&0xFF, (n>>16)&0xFF, (n>>8)&0xFF, n&0xFF])
+
+def cbor_map1(k: int, v: int) -> bytes:
+    return bytes([0xA1]) + cbor_uint(k) + cbor_uint(v)
+
+def cbor_map2(k0: int, v0: int, k1: int, v1: int) -> bytes:
+    return bytes([0xA2]) + cbor_uint(k0) + cbor_uint(v0) + cbor_uint(k1) + cbor_uint(v1)
+
+# Signal-specific args schemas:
+#   MUTE / UNMUTE  → {0: target_member_id}
+#   ROLE_CHANGE    → {0: target_member_id, 1: new_role_id}
+#   STREAM_START / STREAM_STOP → {0: stream_type}
+#   CODEC_UPDATE   → {0: codec_id}
+#   JOIN / LEAVE   → no args required
+
+with GspClient.create() as gsp_alice:
+    # Mute member 3 (no role_claim needed for self-moderation)
+    frame = gsp_alice.send(
+        alice_node, alice_mls,
+        target=0,  # 0 = broadcast
+        signal=SignalType.MUTE,
+        role_claim=0,
+        request_id=1,
+        args=cbor_map1(0, 3),  # {0: target_member_id=3}
+    )
+```
+
+## MLS multi-member group pattern
+
+When inviting a member to an **existing** group (not the first invite), use
+`invite_full` so that existing members can process the commit:
+
+```python
+# Alice adds Carol to an alice+bob group
+commit, welcome = alice_mls.invite_full(carol_mls.export_key_package())
+alice_mls.finalize_commit()          # alice's epoch advances
+bob_mls.process_message(commit)      # bob stages the commit
+bob_mls.finalize_commit()            # bob's epoch advances to match alice
+carol_mls.accept_welcome(welcome)    # carol joins
+assert alice_mls.epoch == bob_mls.epoch == carol_mls.epoch
 ```
 
 ## License

{gbp_stack-1.2.3 → gbp_stack-1.4.0}/README.md

@@ -37,11 +37,23 @@ Beyond the protocol clients, the package ships ready-made helpers:
 * `SFrameSession` + `SFrameEncryptor` — SFrame (draft-ietf-sframe-enc) E2EE
   for GAP audio frames; per-sender AES-GCM keys derived from MLS exporter,
   1024-entry sliding-window replay protection.
+* `encode_gbp_frame` — low-level helper to construct a raw CBOR GBP frame.
+* `lookup_error` — return the CBOR `ErrorObject` for a known error code.
+
+### Coordinator events
+
+`NodeEvent` surfaces three new event kinds for coordinator election:
+
+| `kind` | Extra fields | Meaning |
+|--------|-------------|---------|
+| `coordinator_election_needed` | — | The local node should initiate GSP `COORDINATOR_CLAIM` |
+| `became_coordinator` | — | This node won the election |
+| `coordinator_claim` | `claimant` | A peer sent `COORDINATOR_CLAIM` with this member id |
 
 ## Install
 
 ```sh
-pip install gbp-stack==1.2.3
+pip install gbp-stack==1.4.0
 ```
 
 ## Quick start
@@ -53,7 +65,7 @@ with MlsContext.create("alice") as alice_mls, \
      MlsContext.create("bob")   as bob_mls:
 
     bob_kp  = bob_mls.export_key_package()
-    welcome = alice_mls.invite(bob_kp)
+    welcome = alice_mls.invite(bob_kp)       # alice auto-finalizes; epoch advances to 1
     bob_mls.accept_welcome(welcome)
 
     group_id = alice_mls.group_id
@@ -68,8 +80,67 @@ with MlsContext.create("alice") as alice_mls, \
         frame = gtp_alice.send(alice, alice_mls, target=2,
                                 message_id=0xCAFE_F00D, text="hello")
         for ev in bob.on_wire(bob_mls, frame.wire):
-            if ev.kind == "payload_received" and ev.stream_type == 2:
-                print(gtp_bob.accept(ev.plaintext).text)
+            if ev.kind == "payload_received" and ev.stream_type == 2:  # StreamType.Text
+                result = gtp_bob.accept(ev.plaintext, bob_mls.epoch)
+                print(result.text)   # → "hello"
+                # result.status is "new" (first message from this sender)
+                # subsequent messages → "new"; duplicates → "duplicate"
+```
+
+## GSP signals with per-signal arguments
+
+Signals that target a specific member or resource require CBOR-encoded `args`.
+The `send` method accepts an optional `args: bytes` keyword argument.
+
+```python
+import struct
+from gbp_stack import GspClient, SignalType
+
+# Minimal CBOR helpers
+def cbor_uint(n: int) -> bytes:
+    if n <= 23:     return bytes([n])
+    if n <= 0xFF:   return bytes([0x18, n])
+    if n <= 0xFFFF: return bytes([0x19, n >> 8, n & 0xFF])
+    return bytes([0x1A, (n>>24)&0xFF, (n>>16)&0xFF, (n>>8)&0xFF, n&0xFF])
+
+def cbor_map1(k: int, v: int) -> bytes:
+    return bytes([0xA1]) + cbor_uint(k) + cbor_uint(v)
+
+def cbor_map2(k0: int, v0: int, k1: int, v1: int) -> bytes:
+    return bytes([0xA2]) + cbor_uint(k0) + cbor_uint(v0) + cbor_uint(k1) + cbor_uint(v1)
+
+# Signal-specific args schemas:
+#   MUTE / UNMUTE  → {0: target_member_id}
+#   ROLE_CHANGE    → {0: target_member_id, 1: new_role_id}
+#   STREAM_START / STREAM_STOP → {0: stream_type}
+#   CODEC_UPDATE   → {0: codec_id}
+#   JOIN / LEAVE   → no args required
+
+with GspClient.create() as gsp_alice:
+    # Mute member 3 (no role_claim needed for self-moderation)
+    frame = gsp_alice.send(
+        alice_node, alice_mls,
+        target=0,  # 0 = broadcast
+        signal=SignalType.MUTE,
+        role_claim=0,
+        request_id=1,
+        args=cbor_map1(0, 3),  # {0: target_member_id=3}
+    )
+```
+
+## MLS multi-member group pattern
+
+When inviting a member to an **existing** group (not the first invite), use
+`invite_full` so that existing members can process the commit:
+
+```python
+# Alice adds Carol to an alice+bob group
+commit, welcome = alice_mls.invite_full(carol_mls.export_key_package())
+alice_mls.finalize_commit()          # alice's epoch advances
+bob_mls.process_message(commit)      # bob stages the commit
+bob_mls.finalize_commit()            # bob's epoch advances to match alice
+carol_mls.accept_welcome(welcome)    # carol joins
+assert alice_mls.epoch == bob_mls.epoch == carol_mls.epoch
 ```
 
 ## License

{gbp_stack-1.2.3 → gbp_stack-1.4.0}/gbp_stack/__init__.py

@@ -20,7 +20,7 @@ README for a worked example.
 from ._native import last_error, version
 from .capabilities import CapabilitiesNegotiator
 from .gap_client import GapAcceptResult, GapClient
-from .gbp_node import GroupNode, NodeEvent, NodeState, OutboundFrame, StreamType
+from .gbp_node import GroupNode, NodeEvent, NodeState, OutboundFrame, StreamType, encode_gbp_frame, lookup_error
 from .gsp_client import GspAcceptResult, GspClient, SignalType
 from .gtp_client import GtpAcceptResult, GtpClient
 from .history import MessageEntry, MessageHistory, Watermark
@@ -66,8 +66,10 @@ __all__ = [
     "SignalType",
     "StreamType",
     "Watermark",
+    "encode_gbp_frame",
     "last_error",
+    "lookup_error",
     "version",
 ]
 
-__version__ = "1.2.3"
+__version__ = "1.4.0"

{gbp_stack-1.2.3 → gbp_stack-1.4.0}/gbp_stack/_native.py

@@ -153,6 +153,11 @@ gsp_client_send = _bind(
     GbpBuffer,
     [c_int32, c_int32, c_int32, c_uint32, c_uint32, c_uint32, c_uint32],
 )
+gsp_client_send_with_args = _bind(
+    "gsp_client_send_with_args",
+    GbpBuffer,
+    [c_int32, c_int32, c_int32, c_uint32, c_uint32, c_uint32, c_uint32, c_void_p, c_size_t],
+)
 gsp_client_accept = _bind("gsp_client_accept", c_void_p, [c_int32, c_uint64, c_void_p, c_size_t])
 
 # ── SFrame ────────────────────────────────────────────────────────────────────
@@ -175,6 +180,25 @@ gbp_sframe_decrypt = _bind(
     [c_int32, c_void_p, c_size_t, c_void_p, c_size_t, ctypes.POINTER(c_uint32)],
 )
 
+gbp_frame_encode_v = _bind(
+    "gbp_frame_encode_v",
+    GbpBuffer,
+    [
+        c_uint8,   # version
+        c_void_p,  # group_id_16
+        c_uint64,  # epoch
+        c_uint32,  # transition_id
+        c_uint32,  # stream_type
+        c_uint32,  # stream_id
+        c_uint16,  # flags
+        c_uint32,  # sequence_no
+        c_void_p,  # payload_ptr
+        c_size_t,  # payload_len
+    ],
+)
+
+gbp_error_lookup = _bind("gbp_error_lookup", GbpBuffer, [c_uint16])
+
 
 def take_buffer(buf: GbpBuffer) -> bytes:
     """Copy a returned :class:`GbpBuffer` into a ``bytes`` object and free it."""

{gbp_stack-1.2.3 → gbp_stack-1.4.0}/gbp_stack/gbp_node.py

@@ -69,7 +69,12 @@ class NodeEvent:
     * ``control`` — populates ``sender``, ``opcode`` and ``transition_id``;
     * ``error`` — populates ``code``, ``code_hex``, ``class_``, ``retryable``,
       ``fatal`` and ``reason``;
-    * ``epoch_advanced`` — populates ``epoch`` and ``transition_id``.
+    * ``epoch_advanced`` — populates ``epoch`` and ``transition_id``;
+    * ``coordinator_election_needed`` — no extra fields; the local node should
+      start the coordinator-election handshake (GSP ``COORDINATOR_CLAIM``);
+    * ``became_coordinator`` — no extra fields; this node won the election;
+    * ``coordinator_claim`` — populates ``claimant`` (member id of the peer
+      that sent a ``COORDINATOR_CLAIM`` signal).
     """
 
     kind: str
@@ -92,6 +97,7 @@ class NodeEvent:
     fatal: Optional[bool] = None
     reason: Optional[str] = None
     epoch: Optional[int] = None
+    claimant: Optional[int] = None
 
     @classmethod
     def _from_dict(cls, d: dict) -> "NodeEvent":
@@ -118,6 +124,7 @@ class NodeEvent:
             fatal=d.get("fatal"),
             reason=d.get("reason"),
             epoch=d.get("epoch"),
+            claimant=d.get("claimant"),
         )
 
 
@@ -137,6 +144,51 @@ def _unpack(buf: _n.GbpBuffer, what: str) -> OutboundFrame:
     return OutboundFrame(target=target, wire=raw[4:])
 
 
+def encode_gbp_frame(
+    version: int,
+    group_id: bytes,
+    epoch: int,
+    transition_id: int,
+    stream_type: int,
+    stream_id: int,
+    flags: int,
+    sequence_no: int,
+    payload: bytes,
+) -> bytes:
+    """Encode a raw GBP frame to CBOR bytes.
+
+    Low-level helper — most callers should use :meth:`GroupNode.send_control`
+    or the sub-protocol ``send`` methods instead.
+    """
+    if len(group_id) != 16:
+        raise ValueError("group_id must be 16 bytes")
+    gid = (ctypes.c_uint8 * 16).from_buffer_copy(group_id)
+
+    def call(ptr, length):
+        return _n.gbp_frame_encode_v(
+            version,
+            ctypes.cast(gid, ctypes.c_void_p),
+            epoch,
+            transition_id,
+            stream_type,
+            stream_id,
+            flags,
+            sequence_no,
+            ptr,
+            length,
+        )
+
+    buf = _n.call_with_bytes(payload, call)
+    return _n.take_buffer(buf)
+
+
+def lookup_error(code: int) -> Optional[bytes]:
+    """Return the CBOR-encoded ``ErrorObject`` for *code*, or ``None`` if unknown."""
+    buf = _n.gbp_error_lookup(code)
+    data = _n.take_buffer(buf)
+    return data if data else None
+
+
 class GroupNode:
     """GBP-layer group node.
 

{gbp_stack-1.2.3 → gbp_stack-1.4.0}/gbp_stack/gsp_client.py

@@ -85,12 +85,20 @@ class GspClient:
         signal: SignalType,
         role_claim: int,
         request_id: int,
+        args: bytes = b"",
     ) -> OutboundFrame:
-        """Send a signal."""
-        buf = _n.gsp_client_send(
-            self._handle, node.handle, mls.handle, target,
-            int(signal), role_claim, request_id,
-        )
+        """Send a signal.
+
+        ``args`` carries opcode-specific CBOR-encoded arguments required by
+        signals such as MUTE/UNMUTE (``{0: target_member_id}``),
+        ROLE_CHANGE (``{0: target_member_id, 1: new_role_id}``), etc.
+        """
+        def do_send(ptr, length):
+            return _n.gsp_client_send_with_args(
+                self._handle, node.handle, mls.handle, target,
+                int(signal), role_claim, request_id, ptr, length,
+            )
+        buf = _n.call_with_bytes(args, do_send)
         return _unpack(buf, "gsp_client_send")
 
     def accept(self, plaintext: bytes, current_epoch: int) -> GspAcceptResult:

{gbp_stack-1.2.3 → gbp_stack-1.4.0}/gbp_stack.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gbp-stack
-Version: 1.2.3
+Version: 1.4.0
 Summary: Python bindings for the Group Protocol Stack: a layered, end-to-end encrypted group-messaging protocol family built on top of MLS (RFC 9420).
 Author: Group Protocol Stack contributors
 License: Apache-2.0
@@ -61,11 +61,23 @@ Beyond the protocol clients, the package ships ready-made helpers:
 * `SFrameSession` + `SFrameEncryptor` — SFrame (draft-ietf-sframe-enc) E2EE
   for GAP audio frames; per-sender AES-GCM keys derived from MLS exporter,
   1024-entry sliding-window replay protection.
+* `encode_gbp_frame` — low-level helper to construct a raw CBOR GBP frame.
+* `lookup_error` — return the CBOR `ErrorObject` for a known error code.
+
+### Coordinator events
+
+`NodeEvent` surfaces three new event kinds for coordinator election:
+
+| `kind` | Extra fields | Meaning |
+|--------|-------------|---------|
+| `coordinator_election_needed` | — | The local node should initiate GSP `COORDINATOR_CLAIM` |
+| `became_coordinator` | — | This node won the election |
+| `coordinator_claim` | `claimant` | A peer sent `COORDINATOR_CLAIM` with this member id |
 
 ## Install
 
 ```sh
-pip install gbp-stack==1.2.3
+pip install gbp-stack==1.4.0
 ```
 
 ## Quick start
@@ -77,7 +89,7 @@ with MlsContext.create("alice") as alice_mls, \
      MlsContext.create("bob")   as bob_mls:
 
     bob_kp  = bob_mls.export_key_package()
-    welcome = alice_mls.invite(bob_kp)
+    welcome = alice_mls.invite(bob_kp)       # alice auto-finalizes; epoch advances to 1
     bob_mls.accept_welcome(welcome)
 
     group_id = alice_mls.group_id
@@ -92,8 +104,67 @@ with MlsContext.create("alice") as alice_mls, \
         frame = gtp_alice.send(alice, alice_mls, target=2,
                                 message_id=0xCAFE_F00D, text="hello")
         for ev in bob.on_wire(bob_mls, frame.wire):
-            if ev.kind == "payload_received" and ev.stream_type == 2:
-                print(gtp_bob.accept(ev.plaintext).text)
+            if ev.kind == "payload_received" and ev.stream_type == 2:  # StreamType.Text
+                result = gtp_bob.accept(ev.plaintext, bob_mls.epoch)
+                print(result.text)   # → "hello"
+                # result.status is "new" (first message from this sender)
+                # subsequent messages → "new"; duplicates → "duplicate"
+```
+
+## GSP signals with per-signal arguments
+
+Signals that target a specific member or resource require CBOR-encoded `args`.
+The `send` method accepts an optional `args: bytes` keyword argument.
+
+```python
+import struct
+from gbp_stack import GspClient, SignalType
+
+# Minimal CBOR helpers
+def cbor_uint(n: int) -> bytes:
+    if n <= 23:     return bytes([n])
+    if n <= 0xFF:   return bytes([0x18, n])
+    if n <= 0xFFFF: return bytes([0x19, n >> 8, n & 0xFF])
+    return bytes([0x1A, (n>>24)&0xFF, (n>>16)&0xFF, (n>>8)&0xFF, n&0xFF])
+
+def cbor_map1(k: int, v: int) -> bytes:
+    return bytes([0xA1]) + cbor_uint(k) + cbor_uint(v)
+
+def cbor_map2(k0: int, v0: int, k1: int, v1: int) -> bytes:
+    return bytes([0xA2]) + cbor_uint(k0) + cbor_uint(v0) + cbor_uint(k1) + cbor_uint(v1)
+
+# Signal-specific args schemas:
+#   MUTE / UNMUTE  → {0: target_member_id}
+#   ROLE_CHANGE    → {0: target_member_id, 1: new_role_id}
+#   STREAM_START / STREAM_STOP → {0: stream_type}
+#   CODEC_UPDATE   → {0: codec_id}
+#   JOIN / LEAVE   → no args required
+
+with GspClient.create() as gsp_alice:
+    # Mute member 3 (no role_claim needed for self-moderation)
+    frame = gsp_alice.send(
+        alice_node, alice_mls,
+        target=0,  # 0 = broadcast
+        signal=SignalType.MUTE,
+        role_claim=0,
+        request_id=1,
+        args=cbor_map1(0, 3),  # {0: target_member_id=3}
+    )
+```
+
+## MLS multi-member group pattern
+
+When inviting a member to an **existing** group (not the first invite), use
+`invite_full` so that existing members can process the commit:
+
+```python
+# Alice adds Carol to an alice+bob group
+commit, welcome = alice_mls.invite_full(carol_mls.export_key_package())
+alice_mls.finalize_commit()          # alice's epoch advances
+bob_mls.process_message(commit)      # bob stages the commit
+bob_mls.finalize_commit()            # bob's epoch advances to match alice
+carol_mls.accept_welcome(welcome)    # carol joins
+assert alice_mls.epoch == bob_mls.epoch == carol_mls.epoch
 ```
 
 ## License

{gbp_stack-1.2.3 → gbp_stack-1.4.0}/gbp_stack.egg-info/SOURCES.txt

@@ -16,4 +16,5 @@ gbp_stack/sframe_session.py
 gbp_stack.egg-info/PKG-INFO
 gbp_stack.egg-info/SOURCES.txt
 gbp_stack.egg-info/dependency_links.txt
-gbp_stack.egg-info/top_level.txt
+gbp_stack.egg-info/top_level.txt
+tests/test_integration.py

{gbp_stack-1.2.3 → gbp_stack-1.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "gbp-stack"
-version = "1.2.3"
+version = "1.4.0"
 description = "Python bindings for the Group Protocol Stack: a layered, end-to-end encrypted group-messaging protocol family built on top of MLS (RFC 9420)."
 readme = "README.md"
 requires-python = ">=3.9"