gbp-stack 0.2.0__tar.gz

gbp_stack-0.2.0/PKG-INFO

@@ -0,0 +1,79 @@
+Metadata-Version: 2.4
+Name: gbp-stack
+Version: 0.2.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
+Project-URL: Homepage, https://github.com/F000NKKK/Group-Protocol-Stack
+Project-URL: Repository, https://github.com/F000NKKK/Group-Protocol-Stack
+Project-URL: Documentation, https://github.com/F000NKKK/Group-Protocol-Stack#readme
+Project-URL: Issues, https://github.com/F000NKKK/Group-Protocol-Stack/issues
+Keywords: mls,rfc9420,e2ee,group-messaging,chat,voice,signaling,cryptography,ffi
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Security :: Cryptography
+Classifier: Topic :: System :: Networking
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# gbp-stack — Python bindings for the Group Protocol Stack
+
+[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://github.com/F000NKKK/Group-Protocol-Stack/blob/main/LICENSE)
+
+Python bindings for the [Group Protocol Stack](https://github.com/F000NKKK/Group-Protocol-Stack):
+a layered, end-to-end encrypted group-messaging protocol family built on top
+of [MLS (RFC 9420)](https://www.rfc-editor.org/rfc/rfc9420).
+
+This package wraps the native `gbp_stack` shared library through `ctypes`.
+The wheel for each supported platform bundles the appropriate native binary
+under `gbp_stack/_native/<rid>/`.
+
+## Layers
+
+```
+┌── application ──────────────────────────────────────────────────────┐
+│   GtpClient · GapClient · GspClient   (TCP / UDP / SCTP-like)       │
+├──────────────────────────────────────────────────────────────────────┤
+│   GroupNode (GBP — IP-like base)                                    │
+├──────────────────────────────────────────────────────────────────────┤
+│   MlsContext (RFC 9420)                                             │
+└──────────────────────────────────────────────────────────────────────┘
+```
+
+## Quick start
+
+```python
+from gbp_stack import MlsContext, GroupNode, GtpClient
+
+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)
+    bob_mls.accept_welcome(welcome)
+
+    group_id = alice_mls.group_id
+    with GroupNode.create(member_id=1, group_id=group_id) as alice, \
+         GroupNode.create(member_id=2, group_id=group_id) as bob, \
+         GtpClient.create() as gtp_alice, \
+         GtpClient.create() as gtp_bob:
+
+        alice.bootstrap_as_creator(alice_mls.epoch)
+        bob.bootstrap_as_joiner(bob_mls.epoch)
+
+        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)
+```
+
+## License
+
+Licensed under [Apache License, Version 2.0](https://github.com/F000NKKK/Group-Protocol-Stack/blob/main/LICENSE).

gbp_stack-0.2.0/README.md

@@ -0,0 +1,55 @@
+# gbp-stack — Python bindings for the Group Protocol Stack
+
+[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://github.com/F000NKKK/Group-Protocol-Stack/blob/main/LICENSE)
+
+Python bindings for the [Group Protocol Stack](https://github.com/F000NKKK/Group-Protocol-Stack):
+a layered, end-to-end encrypted group-messaging protocol family built on top
+of [MLS (RFC 9420)](https://www.rfc-editor.org/rfc/rfc9420).
+
+This package wraps the native `gbp_stack` shared library through `ctypes`.
+The wheel for each supported platform bundles the appropriate native binary
+under `gbp_stack/_native/<rid>/`.
+
+## Layers
+
+```
+┌── application ──────────────────────────────────────────────────────┐
+│   GtpClient · GapClient · GspClient   (TCP / UDP / SCTP-like)       │
+├──────────────────────────────────────────────────────────────────────┤
+│   GroupNode (GBP — IP-like base)                                    │
+├──────────────────────────────────────────────────────────────────────┤
+│   MlsContext (RFC 9420)                                             │
+└──────────────────────────────────────────────────────────────────────┘
+```
+
+## Quick start
+
+```python
+from gbp_stack import MlsContext, GroupNode, GtpClient
+
+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)
+    bob_mls.accept_welcome(welcome)
+
+    group_id = alice_mls.group_id
+    with GroupNode.create(member_id=1, group_id=group_id) as alice, \
+         GroupNode.create(member_id=2, group_id=group_id) as bob, \
+         GtpClient.create() as gtp_alice, \
+         GtpClient.create() as gtp_bob:
+
+        alice.bootstrap_as_creator(alice_mls.epoch)
+        bob.bootstrap_as_joiner(bob_mls.epoch)
+
+        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)
+```
+
+## License
+
+Licensed under [Apache License, Version 2.0](https://github.com/F000NKKK/Group-Protocol-Stack/blob/main/LICENSE).

gbp_stack-0.2.0/gbp_stack/__init__.py

@@ -0,0 +1,40 @@
+"""Python bindings for the Group Protocol Stack.
+
+This package exposes a high-level Python API on top of the native
+``gbp_stack`` shared library:
+
+* :class:`MlsContext` — RFC 9420 MLS context.
+* :class:`GroupNode` — GBP-layer group node (the IP-like base).
+* :class:`GtpClient`, :class:`GapClient`, :class:`GspClient` — sub-protocol
+  clients (text, audio, signalling).
+
+See :func:`version` for the underlying library version and the project
+README for a worked example.
+"""
+
+from .gbp_node import GroupNode, NodeEvent, NodeState, OutboundFrame, StreamType
+from .gap_client import GapAcceptResult, GapClient
+from .gsp_client import GspAcceptResult, GspClient, SignalType
+from .gtp_client import GtpAcceptResult, GtpClient
+from .mls_context import MlsContext
+from ._native import last_error, version
+
+__all__ = [
+    "GapAcceptResult",
+    "GapClient",
+    "GroupNode",
+    "GspAcceptResult",
+    "GspClient",
+    "GtpAcceptResult",
+    "GtpClient",
+    "MlsContext",
+    "NodeEvent",
+    "NodeState",
+    "OutboundFrame",
+    "SignalType",
+    "StreamType",
+    "last_error",
+    "version",
+]
+
+__version__ = "0.2.0"

gbp_stack-0.2.0/gbp_stack/_native.py

@@ -0,0 +1,189 @@
+"""Low-level ctypes bindings to the native ``gbp_stack`` shared library.
+
+The library is loaded from a platform-specific subdirectory of
+``gbp_stack/_native/`` (so it can be packaged inside the wheel), with a
+fallback to the OS loader path. Call sites should not depend on the symbols
+in this module directly — use the high-level wrappers in :mod:`gbp_stack`.
+"""
+
+from __future__ import annotations
+
+import ctypes
+import os
+import platform
+from ctypes import (
+    Structure,
+    c_bool,
+    c_char_p,
+    c_int32,
+    c_size_t,
+    c_uint8,
+    c_uint16,
+    c_uint32,
+    c_uint64,
+    c_void_p,
+)
+from typing import Iterable
+
+
+def _candidate_paths() -> Iterable[str]:
+    here = os.path.dirname(os.path.abspath(__file__))
+    system = platform.system().lower()
+    machine = platform.machine().lower()
+    if system == "windows":
+        rid = "win-x64" if machine in ("amd64", "x86_64") else f"win-{machine}"
+        name = "gbp_stack.dll"
+    elif system == "darwin":
+        rid = "osx-arm64" if machine == "arm64" else "osx-x64"
+        name = "libgbp_stack.dylib"
+    else:
+        rid = "linux-x64" if machine in ("x86_64", "amd64") else f"linux-{machine}"
+        name = "libgbp_stack.so"
+    yield os.path.join(here, "_native", rid, name)
+    yield os.path.join(here, "_native", name)
+    yield name
+
+
+def _load() -> ctypes.CDLL:
+    last_err: OSError | None = None
+    for path in _candidate_paths():
+        try:
+            return ctypes.CDLL(path)
+        except OSError as e:
+            last_err = e
+    raise OSError(
+        "failed to load native gbp_stack library; tried: "
+        + ", ".join(_candidate_paths())
+        + (f"; last error: {last_err}" if last_err else "")
+    )
+
+
+_lib = _load()
+
+
+class GbpBuffer(Structure):
+    """``(ptr, len, cap)`` triple matching the FFI ``GbpBuffer`` struct."""
+
+    _fields_ = [
+        ("ptr", c_void_p),
+        ("len", c_size_t),
+        ("cap", c_size_t),
+    ]
+
+
+def _bind(name: str, restype, argtypes):
+    fn = getattr(_lib, name)
+    fn.restype = restype
+    fn.argtypes = argtypes
+    return fn
+
+
+gbp_buffer_free = _bind("gbp_buffer_free", None, [GbpBuffer])
+gbp_string_free = _bind("gbp_string_free", None, [c_void_p])
+_gbp_last_error = _bind("gbp_last_error", c_void_p, [])
+_gbp_version = _bind("gbp_version", c_void_p, [])
+
+gbp_mls_create = _bind("gbp_mls_create", c_int32, [c_void_p, c_size_t])
+gbp_mls_destroy = _bind("gbp_mls_destroy", None, [c_int32])
+gbp_mls_epoch = _bind("gbp_mls_epoch", c_uint64, [c_int32])
+gbp_mls_group_id = _bind("gbp_mls_group_id", c_bool, [c_int32, c_void_p])
+gbp_mls_export_key_package = _bind("gbp_mls_export_key_package", GbpBuffer, [c_int32])
+gbp_mls_invite = _bind("gbp_mls_invite", GbpBuffer, [c_int32, c_void_p, c_size_t])
+gbp_mls_accept_welcome = _bind(
+    "gbp_mls_accept_welcome", c_bool, [c_int32, c_void_p, c_size_t]
+)
+
+gbp_node_create = _bind("gbp_node_create", c_int32, [c_uint32, c_void_p])
+gbp_node_destroy = _bind("gbp_node_destroy", None, [c_int32])
+gbp_node_bootstrap_creator = _bind("gbp_node_bootstrap_creator", c_bool, [c_int32, c_uint64])
+gbp_node_bootstrap_joiner = _bind("gbp_node_bootstrap_joiner", c_bool, [c_int32, c_uint64])
+gbp_node_state = _bind("gbp_node_state", c_uint32, [c_int32])
+gbp_node_epoch = _bind("gbp_node_epoch", c_uint64, [c_int32])
+gbp_node_last_transition_id = _bind("gbp_node_last_transition_id", c_uint32, [c_int32])
+gbp_node_set_epoch = _bind("gbp_node_set_epoch", c_bool, [c_int32, c_uint64])
+gbp_node_apply_transition = _bind("gbp_node_apply_transition", c_bool, [c_int32, c_uint32])
+gbp_node_send_control = _bind(
+    "gbp_node_send_control",
+    GbpBuffer,
+    [c_int32, c_int32, c_uint32, c_uint16, c_uint32, c_uint32, c_void_p, c_size_t],
+)
+gbp_node_on_wire = _bind(
+    "gbp_node_on_wire", c_void_p, [c_int32, c_int32, c_void_p, c_size_t]
+)
+gbp_node_drain_events = _bind("gbp_node_drain_events", c_void_p, [c_int32])
+
+gtp_client_create = _bind("gtp_client_create", c_int32, [])
+gtp_client_destroy = _bind("gtp_client_destroy", None, [c_int32])
+gtp_client_reset = _bind("gtp_client_reset", None, [c_int32])
+gtp_client_send = _bind(
+    "gtp_client_send",
+    GbpBuffer,
+    [c_int32, c_int32, c_int32, c_uint32, c_uint64, c_void_p, c_size_t],
+)
+gtp_client_accept = _bind("gtp_client_accept", c_void_p, [c_int32, c_void_p, c_size_t])
+
+gap_client_create = _bind("gap_client_create", c_int32, [])
+gap_client_destroy = _bind("gap_client_destroy", None, [c_int32])
+gap_client_reset = _bind("gap_client_reset", None, [c_int32])
+gap_client_send = _bind(
+    "gap_client_send",
+    GbpBuffer,
+    [c_int32, c_int32, c_int32, c_uint32, c_uint32, c_uint64, c_void_p, c_size_t],
+)
+gap_client_accept = _bind(
+    "gap_client_accept", c_void_p, [c_int32, c_uint64, c_void_p, c_size_t]
+)
+
+gsp_client_create = _bind("gsp_client_create", c_int32, [])
+gsp_client_destroy = _bind("gsp_client_destroy", None, [c_int32])
+gsp_client_reset = _bind("gsp_client_reset", None, [c_int32])
+gsp_client_send = _bind(
+    "gsp_client_send",
+    GbpBuffer,
+    [c_int32, c_int32, c_int32, c_uint32, c_uint32, c_uint32, c_uint32],
+)
+gsp_client_accept = _bind("gsp_client_accept", c_void_p, [c_int32, c_void_p, c_size_t])
+
+
+def take_buffer(buf: GbpBuffer) -> bytes:
+    """Copy a returned :class:`GbpBuffer` into a ``bytes`` object and free it."""
+    if not buf.ptr or buf.len == 0:
+        gbp_buffer_free(buf)
+        return b""
+    raw = ctypes.string_at(buf.ptr, buf.len)
+    gbp_buffer_free(buf)
+    return raw
+
+
+def take_cstring(ptr: int) -> str:
+    """Copy a returned C string into a ``str`` and free it."""
+    if not ptr:
+        return ""
+    try:
+        raw = ctypes.cast(ptr, c_char_p).value
+        return raw.decode("utf-8") if raw is not None else ""
+    finally:
+        gbp_string_free(ptr)
+
+
+def last_error() -> str:
+    """Return the text of the last FFI error on this thread."""
+    return take_cstring(_gbp_last_error())
+
+
+def version() -> str:
+    """Return the native library version string."""
+    return take_cstring(_gbp_version())
+
+
+def call_with_bytes(data: bytes, fn):
+    """Invoke ``fn(ptr, length)`` with a temporary ctypes buffer.
+
+    The buffer's lifetime is bounded to this call; ``fn`` MUST NOT retain
+    ``ptr`` past its return.
+    """
+    length = len(data)
+    if length == 0:
+        return fn(None, 0)
+    arr = (c_uint8 * length).from_buffer_copy(data)
+    return fn(ctypes.cast(arr, c_void_p), length)

gbp_stack-0.2.0/gbp_stack/gap_client.py

@@ -0,0 +1,106 @@
+"""Group Audio Protocol client wrapper."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import Optional
+
+from . import _native as _n
+from .gbp_node import GroupNode, OutboundFrame, _unpack
+from .mls_context import MlsContext
+
+
+@dataclass(frozen=True)
+class GapAcceptResult:
+    """Outcome of :meth:`GapClient.accept`."""
+
+    status: str
+    source: Optional[int] = None
+    seq: Optional[int] = None
+    bytes_: Optional[int] = None
+    reason: Optional[str] = None
+
+    @classmethod
+    def _parse(cls, json_text: str) -> "GapAcceptResult":
+        d = json.loads(json_text) if json_text else {}
+        return cls(
+            status=d.get("status", "?"),
+            source=d.get("source"),
+            seq=d.get("seq"),
+            bytes_=d.get("bytes"),
+            reason=d.get("reason"),
+        )
+
+
+class GapClient:
+    """Group Audio Protocol client.
+
+    Maintains a per-source ``rtp_sequence`` window and validates ``key_phase``
+    against the current group epoch.
+    """
+
+    __slots__ = ("_handle",)
+
+    def __init__(self, handle: int) -> None:
+        self._handle = handle
+
+    @classmethod
+    def create(cls) -> "GapClient":
+        """Create a fresh GAP client."""
+        h = _n.gap_client_create()
+        if h <= 0:
+            raise OSError("gap_client_create")
+        return cls(h)
+
+    @property
+    def handle(self) -> int:
+        """Native handle (i32)."""
+        return self._handle
+
+    def send(
+        self,
+        node: GroupNode,
+        mls: MlsContext,
+        target: int,
+        media_source_id: int,
+        rtp_timestamp: int,
+        opus: bytes,
+    ) -> OutboundFrame:
+        """Send an Opus audio frame."""
+        def call(ptr, length):
+            return _n.gap_client_send(
+                self._handle, node.handle, mls.handle, target,
+                media_source_id, rtp_timestamp, ptr, length,
+            )
+        buf = _n.call_with_bytes(opus, call)
+        return _unpack(buf, "gap_client_send")
+
+    def accept(self, plaintext: bytes, current_epoch: int) -> GapAcceptResult:
+        """Accept a plaintext payload delivered by the GBP layer."""
+        def call(ptr, length):
+            return _n.gap_client_accept(self._handle, current_epoch, ptr, length)
+        ptr = _n.call_with_bytes(plaintext, call)
+        return GapAcceptResult._parse(_n.take_cstring(ptr))
+
+    def reset(self) -> None:
+        """Clear the replay window. Intended for use after an epoch change."""
+        _n.gap_client_reset(self._handle)
+
+    def close(self) -> None:
+        """Release the native handle. Idempotent."""
+        if self._handle:
+            _n.gap_client_destroy(self._handle)
+            self._handle = 0
+
+    def __enter__(self) -> "GapClient":
+        return self
+
+    def __exit__(self, exc_type, exc, tb) -> None:
+        self.close()
+
+    def __del__(self) -> None:
+        try:
+            self.close()
+        except Exception:
+            pass

gbp_stack-0.2.0/gbp_stack/gbp_node.py

@@ -0,0 +1,256 @@
+"""GBP-layer group node wrapper (the IP-like base)."""
+
+from __future__ import annotations
+
+import base64
+import ctypes
+import enum
+import json
+from dataclasses import dataclass
+from typing import List, Optional
+
+from . import _native as _n
+from .mls_context import MlsContext
+
+
+class StreamType(enum.IntEnum):
+    """Stream class."""
+
+    CONTROL = 0
+    AUDIO = 1
+    TEXT = 2
+    SIGNAL = 3
+
+
+class NodeState(enum.IntEnum):
+    """Node FSM state."""
+
+    IDLE = 0
+    CONNECTING = 1
+    ESTABLISHING_GROUP = 2
+    ACTIVE = 3
+    RESYNCING = 4
+    FAILED = 5
+    CLOSED = 6
+
+
+class ControlOpcode(enum.IntEnum):
+    """Control plane opcode."""
+
+    PREPARE_TRANSITION = 0x0001
+    READY_FOR_TRANSITION = 0x0002
+    EXECUTE_TRANSITION = 0x0003
+    ABORT_TRANSITION = 0x0004
+    GROUP_STATE_DIGEST_REQUEST = 0x0005
+    GROUP_STATE_DIGEST_RESPONSE = 0x0006
+    REPORT_INVALID_COMMIT = 0x0007
+    CAPABILITIES_ADVERTISE = 0x0008
+    ACK = 0x0009
+    NACK = 0x000A
+
+
+@dataclass(frozen=True)
+class OutboundFrame:
+    """Wire frame produced by the native library."""
+
+    target: int
+    wire: bytes
+
+
+@dataclass
+class NodeEvent:
+    """Event surfaced by the GBP layer.
+
+    ``kind`` tells which fields are populated; common kinds are:
+
+    * ``state_changed`` — populates ``from_state`` and ``to_state``;
+    * ``payload_received`` — populates ``stream_type``, ``stream_id``,
+      ``sequence_no``, ``flags`` and ``plaintext``;
+    * ``control`` — populates ``sender``, ``opcode`` and ``transition_id``;
+    * ``error`` — populates ``code``, ``code_hex``, ``class_``, ``retryable``,
+      ``fatal`` and ``reason``;
+    * ``epoch_advanced`` — populates ``epoch`` and ``transition_id``.
+    """
+
+    kind: str
+    from_state: Optional[str] = None
+    to_state: Optional[str] = None
+    stream_type_name: Optional[str] = None
+    stream_type: Optional[StreamType] = None
+    stream_id: Optional[int] = None
+    sequence_no: Optional[int] = None
+    flags: Optional[int] = None
+    plaintext: Optional[bytes] = None
+    sender: Optional[int] = None
+    opcode: Optional[str] = None
+    opcode_code: Optional[int] = None
+    transition_id: Optional[int] = None
+    code: Optional[int] = None
+    code_hex: Optional[str] = None
+    class_: Optional[int] = None
+    retryable: Optional[bool] = None
+    fatal: Optional[bool] = None
+    reason: Optional[str] = None
+    epoch: Optional[int] = None
+
+    @classmethod
+    def _from_dict(cls, d: dict) -> "NodeEvent":
+        st_code = d.get("stream_type_code")
+        plaintext_b64 = d.get("plaintext_b64")
+        return cls(
+            kind=d["kind"],
+            from_state=d.get("from"),
+            to_state=d.get("to"),
+            stream_type_name=d.get("stream_type"),
+            stream_type=StreamType(st_code) if st_code is not None else None,
+            stream_id=d.get("stream_id"),
+            sequence_no=d.get("sequence_no"),
+            flags=d.get("flags"),
+            plaintext=base64.b64decode(plaintext_b64) if plaintext_b64 else None,
+            sender=d.get("from") if isinstance(d.get("from"), int) else None,
+            opcode=d.get("opcode"),
+            opcode_code=d.get("opcode_code"),
+            transition_id=d.get("transition_id"),
+            code=d.get("code"),
+            code_hex=d.get("code_hex"),
+            class_=d.get("class"),
+            retryable=d.get("retryable"),
+            fatal=d.get("fatal"),
+            reason=d.get("reason"),
+            epoch=d.get("epoch"),
+        )
+
+
+def _parse_events(json_text: str) -> List[NodeEvent]:
+    if not json_text or json_text == "[]":
+        return []
+    return [NodeEvent._from_dict(d) for d in json.loads(json_text)]
+
+
+def _unpack(buf: _n.GbpBuffer, what: str) -> OutboundFrame:
+    raw = _n.take_buffer(buf)
+    if not raw:
+        raise OSError(f"{what}: {_n.last_error()}")
+    if len(raw) < 4:
+        raise OSError(f"{what}: buffer too short")
+    target = int.from_bytes(raw[:4], byteorder="little", signed=False)
+    return OutboundFrame(target=target, wire=raw[4:])
+
+
+class GroupNode:
+    """GBP-layer group node.
+
+    Owns the framing, AEAD, replay window, FSM and control plane.
+    Sub-protocol semantics live in :class:`gbp_stack.GtpClient`,
+    :class:`gbp_stack.GapClient` and :class:`gbp_stack.GspClient`.
+    """
+
+    __slots__ = ("_handle", "member_id", "_group_id")
+
+    def __init__(self, handle: int, member_id: int, group_id: bytes) -> None:
+        self._handle = handle
+        self.member_id = member_id
+        self._group_id = bytes(group_id)
+
+    @classmethod
+    def create(cls, member_id: int, group_id: bytes) -> "GroupNode":
+        """Create a node bound to ``group_id`` (which MUST be 16 bytes)."""
+        if len(group_id) != 16:
+            raise ValueError("group_id must be 16 bytes")
+        gid = (ctypes.c_uint8 * 16).from_buffer_copy(group_id)
+        handle = _n.gbp_node_create(member_id, ctypes.cast(gid, ctypes.c_void_p))
+        if handle <= 0:
+            raise OSError(f"node_create: {_n.last_error()}")
+        return cls(handle, member_id, group_id)
+
+    @property
+    def handle(self) -> int:
+        """Native handle (i32)."""
+        return self._handle
+
+    @property
+    def state(self) -> NodeState:
+        """Current FSM state."""
+        return NodeState(_n.gbp_node_state(self._handle))
+
+    @property
+    def epoch(self) -> int:
+        """Current node epoch."""
+        return int(_n.gbp_node_epoch(self._handle))
+
+    @property
+    def last_transition_id(self) -> int:
+        """Last applied ``transition_id``."""
+        return int(_n.gbp_node_last_transition_id(self._handle))
+
+    @property
+    def group_id(self) -> bytes:
+        """16-byte group identifier."""
+        return self._group_id
+
+    def bootstrap_as_creator(self, epoch: int) -> None:
+        """Drive the node from ``IDLE`` to ``ACTIVE`` as a creator."""
+        if not _n.gbp_node_bootstrap_creator(self._handle, epoch):
+            raise OSError(_n.last_error())
+
+    def bootstrap_as_joiner(self, epoch: int) -> None:
+        """Drive the node from ``IDLE`` to ``ACTIVE`` as a joiner."""
+        if not _n.gbp_node_bootstrap_joiner(self._handle, epoch):
+            raise OSError(_n.last_error())
+
+    def set_epoch_for_testing(self, epoch: int) -> None:
+        """Forcibly override ``current_epoch`` (intended for tests of late peers)."""
+        if not _n.gbp_node_set_epoch(self._handle, epoch):
+            raise OSError(_n.last_error())
+
+    def apply_transition(self, transition_id: int) -> None:
+        """Apply an epoch transition locally."""
+        if not _n.gbp_node_apply_transition(self._handle, transition_id):
+            raise OSError(_n.last_error())
+
+    def send_control(
+        self,
+        mls: MlsContext,
+        target: int,
+        opcode: ControlOpcode,
+        transition_id: int,
+        request_id: int,
+        args: bytes = b"",
+    ) -> OutboundFrame:
+        """Send a control plane message on Stream 0."""
+        def call(ptr, length):
+            return _n.gbp_node_send_control(
+                self._handle, mls.handle, target, int(opcode),
+                transition_id, request_id, ptr, length,
+            )
+        buf = _n.call_with_bytes(args, call)
+        return _unpack(buf, "send_control")
+
+    def on_wire(self, mls: MlsContext, wire: bytes) -> List[NodeEvent]:
+        """Feed wire bytes to the node and return the resulting events."""
+        def call(ptr, length):
+            return _n.gbp_node_on_wire(self._handle, mls.handle, ptr, length)
+        ptr = _n.call_with_bytes(wire, call)
+        return _parse_events(_n.take_cstring(ptr))
+
+    def drain_events(self) -> List[NodeEvent]:
+        """Drain queued events without consuming any wire bytes."""
+        return _parse_events(_n.take_cstring(_n.gbp_node_drain_events(self._handle)))
+
+    def close(self) -> None:
+        """Release the native handle. Idempotent."""
+        if self._handle:
+            _n.gbp_node_destroy(self._handle)
+            self._handle = 0
+
+    def __enter__(self) -> "GroupNode":
+        return self
+
+    def __exit__(self, exc_type, exc, tb) -> None:
+        self.close()
+
+    def __del__(self) -> None:
+        try:
+            self.close()
+        except Exception:
+            pass

gbp_stack-0.2.0/gbp_stack/gsp_client.py

@@ -0,0 +1,123 @@
+"""Group Signaling Protocol client wrapper."""
+
+from __future__ import annotations
+
+import enum
+import json
+from dataclasses import dataclass
+from typing import Optional
+
+from . import _native as _n
+from .gbp_node import GroupNode, OutboundFrame, _unpack
+from .mls_context import MlsContext
+
+
+class SignalType(enum.IntEnum):
+    """Signal opcode registry."""
+
+    JOIN = 100
+    LEAVE = 101
+    ROLE_CHANGE = 102
+    MUTE = 200
+    UNMUTE = 201
+    STREAM_START = 300
+    STREAM_STOP = 301
+    CODEC_UPDATE = 400
+
+
+@dataclass(frozen=True)
+class GspAcceptResult:
+    """Outcome of :meth:`GspClient.accept`."""
+
+    status: str
+    signal: Optional[str] = None
+    signal_code: Optional[SignalType] = None
+    sender: Optional[int] = None
+    role_claim: Optional[int] = None
+    request_id: Optional[int] = None
+    reason: Optional[str] = None
+
+    @classmethod
+    def _parse(cls, json_text: str) -> "GspAcceptResult":
+        d = json.loads(json_text) if json_text else {}
+        sc = d.get("signal_code")
+        return cls(
+            status=d.get("status", "?"),
+            signal=d.get("signal"),
+            signal_code=SignalType(sc) if sc is not None else None,
+            sender=d.get("sender"),
+            role_claim=d.get("role_claim"),
+            request_id=d.get("request_id"),
+            reason=d.get("reason"),
+        )
+
+
+class GspClient:
+    """Group Signaling Protocol client.
+
+    Tracks ``request_id`` deduplication and maintains the local membership
+    and mute-list state.
+    """
+
+    __slots__ = ("_handle",)
+
+    def __init__(self, handle: int) -> None:
+        self._handle = handle
+
+    @classmethod
+    def create(cls) -> "GspClient":
+        """Create a fresh GSP client."""
+        h = _n.gsp_client_create()
+        if h <= 0:
+            raise OSError("gsp_client_create")
+        return cls(h)
+
+    @property
+    def handle(self) -> int:
+        """Native handle (i32)."""
+        return self._handle
+
+    def send(
+        self,
+        node: GroupNode,
+        mls: MlsContext,
+        target: int,
+        signal: SignalType,
+        role_claim: int,
+        request_id: int,
+    ) -> OutboundFrame:
+        """Send a signal."""
+        buf = _n.gsp_client_send(
+            self._handle, node.handle, mls.handle, target,
+            int(signal), role_claim, request_id,
+        )
+        return _unpack(buf, "gsp_client_send")
+
+    def accept(self, plaintext: bytes) -> GspAcceptResult:
+        """Accept a plaintext payload delivered by the GBP layer."""
+        def call(ptr, length):
+            return _n.gsp_client_accept(self._handle, ptr, length)
+        ptr = _n.call_with_bytes(plaintext, call)
+        return GspAcceptResult._parse(_n.take_cstring(ptr))
+
+    def reset(self) -> None:
+        """Clear the request-id deduplication set. Intended for use after an epoch change."""
+        _n.gsp_client_reset(self._handle)
+
+    def close(self) -> None:
+        """Release the native handle. Idempotent."""
+        if self._handle:
+            _n.gsp_client_destroy(self._handle)
+            self._handle = 0
+
+    def __enter__(self) -> "GspClient":
+        return self
+
+    def __exit__(self, exc_type, exc, tb) -> None:
+        self.close()
+
+    def __del__(self) -> None:
+        try:
+            self.close()
+        except Exception:
+            pass

gbp_stack-0.2.0/gbp_stack/gtp_client.py

@@ -0,0 +1,104 @@
+"""Group Text Protocol client wrapper."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import Optional
+
+from . import _native as _n
+from .gbp_node import GroupNode, OutboundFrame, _unpack
+from .mls_context import MlsContext
+
+
+@dataclass(frozen=True)
+class GtpAcceptResult:
+    """Outcome of :meth:`GtpClient.accept`."""
+
+    status: str
+    sender: Optional[int] = None
+    message_id: Optional[int] = None
+    text: Optional[str] = None
+    reason: Optional[str] = None
+
+    @classmethod
+    def _parse(cls, json_text: str) -> "GtpAcceptResult":
+        d = json.loads(json_text) if json_text else {}
+        return cls(
+            status=d.get("status", "?"),
+            sender=d.get("sender"),
+            message_id=d.get("message_id"),
+            text=d.get("text"),
+            reason=d.get("reason"),
+        )
+
+
+class GtpClient:
+    """Group Text Protocol client.
+
+    Tracks idempotency by ``(sender_id, message_id)``.
+    """
+
+    __slots__ = ("_handle",)
+
+    def __init__(self, handle: int) -> None:
+        self._handle = handle
+
+    @classmethod
+    def create(cls) -> "GtpClient":
+        """Create a fresh GTP client."""
+        h = _n.gtp_client_create()
+        if h <= 0:
+            raise OSError("gtp_client_create")
+        return cls(h)
+
+    @property
+    def handle(self) -> int:
+        """Native handle (i32)."""
+        return self._handle
+
+    def send(
+        self,
+        node: GroupNode,
+        mls: MlsContext,
+        target: int,
+        message_id: int,
+        text: str,
+    ) -> OutboundFrame:
+        """Send a text message."""
+        data = text.encode("utf-8")
+        def call(ptr, length):
+            return _n.gtp_client_send(
+                self._handle, node.handle, mls.handle, target, message_id, ptr, length
+            )
+        buf = _n.call_with_bytes(data, call)
+        return _unpack(buf, "gtp_client_send")
+
+    def accept(self, plaintext: bytes) -> GtpAcceptResult:
+        """Accept a plaintext payload delivered by the GBP layer."""
+        def call(ptr, length):
+            return _n.gtp_client_accept(self._handle, ptr, length)
+        ptr = _n.call_with_bytes(plaintext, call)
+        return GtpAcceptResult._parse(_n.take_cstring(ptr))
+
+    def reset(self) -> None:
+        """Clear the idempotency state. Intended for use after an epoch change."""
+        _n.gtp_client_reset(self._handle)
+
+    def close(self) -> None:
+        """Release the native handle. Idempotent."""
+        if self._handle:
+            _n.gtp_client_destroy(self._handle)
+            self._handle = 0
+
+    def __enter__(self) -> "GtpClient":
+        return self
+
+    def __exit__(self, exc_type, exc, tb) -> None:
+        self.close()
+
+    def __del__(self) -> None:
+        try:
+            self.close()
+        except Exception:
+            pass

gbp_stack-0.2.0/gbp_stack/mls_context.py

@@ -0,0 +1,93 @@
+"""MLS (RFC 9420) context wrapper."""
+
+from __future__ import annotations
+
+import ctypes
+
+from . import _native as _n
+
+
+class MlsContext:
+    """Managed wrapper around an MLS context owned by the native library.
+
+    Owns a single-member group plus a published ``KeyPackage`` that can be
+    used to invite this member into another group. Always use as a context
+    manager so the native handle is released.
+    """
+
+    __slots__ = ("_handle", "identity")
+
+    def __init__(self, handle: int, identity: str) -> None:
+        self._handle = handle
+        self.identity = identity
+
+    @classmethod
+    def create(cls, identity: str) -> "MlsContext":
+        """Create a fresh MLS context."""
+        data = identity.encode("utf-8")
+        handle = _n.call_with_bytes(data, _n.gbp_mls_create)
+        if handle <= 0:
+            raise OSError(f"gbp_mls_create: {_n.last_error()}")
+        return cls(handle, identity)
+
+    @property
+    def handle(self) -> int:
+        """Native handle (i32)."""
+        return self._handle
+
+    @property
+    def epoch(self) -> int:
+        """Current group epoch."""
+        return int(_n.gbp_mls_epoch(self._handle))
+
+    @property
+    def group_id(self) -> bytes:
+        """16-byte group identifier."""
+        buf = (ctypes.c_uint8 * 16)()
+        if not _n.gbp_mls_group_id(self._handle, ctypes.cast(buf, ctypes.c_void_p)):
+            raise OSError(f"group_id: {_n.last_error()}")
+        return bytes(buf)
+
+    def export_key_package(self) -> bytes:
+        """Export this member's TLS-serialised KeyPackage."""
+        buf = _n.gbp_mls_export_key_package(self._handle)
+        out = _n.take_buffer(buf)
+        if not out:
+            raise OSError(f"export_key_package: {_n.last_error()}")
+        return out
+
+    def invite(self, key_package: bytes) -> bytes:
+        """Invite ``key_package`` into the local group; returns the Welcome."""
+        def call(ptr, length):
+            return _n.gbp_mls_invite(self._handle, ptr, length)
+        buf = _n.call_with_bytes(key_package, call)
+        out = _n.take_buffer(buf)
+        if not out:
+            raise OSError(f"invite: {_n.last_error()}")
+        return out
+
+    def accept_welcome(self, welcome: bytes) -> None:
+        """Replace the local group with the one described by ``welcome``."""
+        def call(ptr, length):
+            return _n.gbp_mls_accept_welcome(self._handle, ptr, length)
+        ok = _n.call_with_bytes(welcome, call)
+        if not ok:
+            raise OSError(f"accept_welcome: {_n.last_error()}")
+
+    def close(self) -> None:
+        """Release the native handle. Idempotent."""
+        if self._handle:
+            _n.gbp_mls_destroy(self._handle)
+            self._handle = 0
+
+    def __enter__(self) -> "MlsContext":
+        return self
+
+    def __exit__(self, exc_type, exc, tb) -> None:
+        self.close()
+
+    def __del__(self) -> None:
+        try:
+            self.close()
+        except Exception:
+            pass

gbp_stack-0.2.0/gbp_stack.egg-info/PKG-INFO

@@ -0,0 +1,79 @@
+Metadata-Version: 2.4
+Name: gbp-stack
+Version: 0.2.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
+Project-URL: Homepage, https://github.com/F000NKKK/Group-Protocol-Stack
+Project-URL: Repository, https://github.com/F000NKKK/Group-Protocol-Stack
+Project-URL: Documentation, https://github.com/F000NKKK/Group-Protocol-Stack#readme
+Project-URL: Issues, https://github.com/F000NKKK/Group-Protocol-Stack/issues
+Keywords: mls,rfc9420,e2ee,group-messaging,chat,voice,signaling,cryptography,ffi
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Security :: Cryptography
+Classifier: Topic :: System :: Networking
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# gbp-stack — Python bindings for the Group Protocol Stack
+
+[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://github.com/F000NKKK/Group-Protocol-Stack/blob/main/LICENSE)
+
+Python bindings for the [Group Protocol Stack](https://github.com/F000NKKK/Group-Protocol-Stack):
+a layered, end-to-end encrypted group-messaging protocol family built on top
+of [MLS (RFC 9420)](https://www.rfc-editor.org/rfc/rfc9420).
+
+This package wraps the native `gbp_stack` shared library through `ctypes`.
+The wheel for each supported platform bundles the appropriate native binary
+under `gbp_stack/_native/<rid>/`.
+
+## Layers
+
+```
+┌── application ──────────────────────────────────────────────────────┐
+│   GtpClient · GapClient · GspClient   (TCP / UDP / SCTP-like)       │
+├──────────────────────────────────────────────────────────────────────┤
+│   GroupNode (GBP — IP-like base)                                    │
+├──────────────────────────────────────────────────────────────────────┤
+│   MlsContext (RFC 9420)                                             │
+└──────────────────────────────────────────────────────────────────────┘
+```
+
+## Quick start
+
+```python
+from gbp_stack import MlsContext, GroupNode, GtpClient
+
+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)
+    bob_mls.accept_welcome(welcome)
+
+    group_id = alice_mls.group_id
+    with GroupNode.create(member_id=1, group_id=group_id) as alice, \
+         GroupNode.create(member_id=2, group_id=group_id) as bob, \
+         GtpClient.create() as gtp_alice, \
+         GtpClient.create() as gtp_bob:
+
+        alice.bootstrap_as_creator(alice_mls.epoch)
+        bob.bootstrap_as_joiner(bob_mls.epoch)
+
+        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)
+```
+
+## License
+
+Licensed under [Apache License, Version 2.0](https://github.com/F000NKKK/Group-Protocol-Stack/blob/main/LICENSE).

gbp_stack-0.2.0/gbp_stack.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+README.md
+pyproject.toml
+setup.py
+gbp_stack/__init__.py
+gbp_stack/_native.py
+gbp_stack/gap_client.py
+gbp_stack/gbp_node.py
+gbp_stack/gsp_client.py
+gbp_stack/gtp_client.py
+gbp_stack/mls_context.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-0.2.0/gbp_stack.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

gbp_stack-0.2.0/gbp_stack.egg-info/top_level.txt

@@ -0,0 +1 @@
+gbp_stack

gbp_stack-0.2.0/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "gbp-stack"
+version = "0.2.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"
+license = { text = "Apache-2.0" }
+authors = [{ name = "Group Protocol Stack contributors" }]
+keywords = ["mls", "rfc9420", "e2ee", "group-messaging", "chat", "voice", "signaling", "cryptography", "ffi"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Operating System :: Microsoft :: Windows",
+    "Operating System :: POSIX :: Linux",
+    "Operating System :: MacOS",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Topic :: Security :: Cryptography",
+    "Topic :: System :: Networking",
+]
+
+[project.urls]
+Homepage      = "https://github.com/F000NKKK/Group-Protocol-Stack"
+Repository    = "https://github.com/F000NKKK/Group-Protocol-Stack"
+Documentation = "https://github.com/F000NKKK/Group-Protocol-Stack#readme"
+Issues        = "https://github.com/F000NKKK/Group-Protocol-Stack/issues"
+
+[tool.setuptools]
+include-package-data = true
+
+[tool.setuptools.packages.find]
+include = ["gbp_stack*"]
+
+[tool.setuptools.package-data]
+"gbp_stack" = [
+    "_native/win-x64/*.dll",
+    "_native/linux-x64/*.so",
+    "_native/osx-x64/*.dylib",
+    "_native/osx-arm64/*.dylib",
+]

gbp_stack-0.2.0/setup.cfg

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

gbp_stack-0.2.0/setup.py

@@ -0,0 +1,22 @@
+"""Setup shim that marks the wheel as platform-specific.
+
+The package ships a native shared library, so the produced wheel must NOT be
+tagged as ``py3-none-any``; it must carry a real platform tag. We do this by
+overriding ``bdist_wheel.root_is_pure``.
+"""
+
+from setuptools import setup
+
+try:
+    from setuptools.command.bdist_wheel import bdist_wheel  # type: ignore
+except ImportError:  # older setuptools
+    from wheel.bdist_wheel import bdist_wheel  # type: ignore
+
+
+class _bdist_wheel(bdist_wheel):  # type: ignore[misc, valid-type]
+    def finalize_options(self) -> None:
+        super().finalize_options()
+        self.root_is_pure = False
+
+
+setup(cmdclass={"bdist_wheel": _bdist_wheel})