gbp-stack — Python bindings for the Group Protocol Stack

License: Apache 2.0

Python bindings for the Group Protocol Stack: a layered, end-to-end encrypted group-messaging protocol family built on top of MLS (RFC 9420).

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)                                             │
└─────────────────────────────────────────────────────────────────────┘

Payload codec

Each sub-protocol payload can be encoded as CBOR (default), Protobuf, or FlatBuffers. Pass PayloadCodec to send and accept; the chosen codec is surfaced in ev.codec on payload_received events.

from gbp_stack import GtpClient, PayloadCodec

frame = gtp_alice.send(alice, alice_mls, target=2, message_id=1,
                       text="hello", codec=PayloadCodec.FLATBUFFERS)
for ev in bob.on_wire(bob_mls, frame.wire):
    if ev.kind == "payload_received":
        codec = ev.codec or PayloadCodec.CBOR
        result = gtp_bob.accept(ev.plaintext, bob_mls.epoch, codec=codec)
        print(result.text)
Value Name Description
0 PayloadCodec.CBOR Default; pf field omitted from wire
1 PayloadCodec.PROTOBUF Protobuf via gbp-proto
2 PayloadCodec.FLATBUFFERS FlatBuffers via gbp-flat; lowest latency

Sub-protocol toolkits

Beyond the protocol clients, the package ships ready-made helpers:

  • MessageHistory + Watermark — bounded GTP message log + per-sender high-water mark for serving and consuming resync requests.
  • JitterBuffer — bounded GAP reorder window keyed by media_source_id, with push, pop_in_order, pop_force and late-frame detection.
  • RoleRegistry + Permissions — bind numeric role ids to permission bit-masks and check them with require / has.
  • CapabilitiesNegotiator — track per-member advertisements and query the intersection, union, group_supports and missing views.
  • 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

pip install gbp-stack==1.9.0

Quick start

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)       # alice auto-finalizes; epoch advances to 1
    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:  # 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.

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:

# 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

Persisting MLS state

Serialise a context so it survives a restart, then restore it later — the restored context is at the same epoch and can send / receive again. The blob holds private key material, so store it encrypted at rest.

blob = mls.export_state()                   # persist (encrypted) to disk
# ... later / after restart ...
with MlsContext.restore_state(blob, "alice") as restored:
    assert restored.epoch == mls.epoch
    assert restored.group_id == mls.group_id

License

Licensed under Apache License, Version 2.0.

Project links

Data verified by PyPI on Aug 4, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (1.9.1)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for F000NK from gravatar.com F000NK

Credits

Author: Group Protocol Stack contributors

GitHub Statistics

Data verified by PyPI on Aug 4, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License

Apache Software License (Apache-2.0)

Requires

Python >=3.9

Tags

mls rfc9420 e2ee group-messaging chat voice signaling cryptography ffi

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

gbp_stack-1.9.0.tar.gz (27.9 kB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

gbp_stack-1.9.0-cp311-cp311-win_arm64.whl (25.4 kB view details)

Uploaded CPython 3.11Windows ARM64

gbp_stack-1.9.0-cp311-cp311-win_amd64.whl (1.4 MB view details)

Uploaded CPython 3.11Windows x86-64

gbp_stack-1.9.0-cp311-cp311-manylinux2014_x86_64.whl (1.4 MB view details)

Uploaded CPython 3.11

gbp_stack-1.9.0-cp311-cp311-manylinux2014_aarch64.whl (25.2 kB view details)

Uploaded CPython 3.11

gbp_stack-1.9.0-cp311-cp311-macosx_11_0_x86_64.whl (1.4 MB view details)

Uploaded CPython 3.11macOS 11.0+ x86-64

gbp_stack-1.9.0-cp311-cp311-macosx_11_0_arm64.whl (1.2 MB view details)

Uploaded CPython 3.11macOS 11.0+ ARM64

File details

Details for the file gbp_stack-1.9.0.tar.gz.

File metadata

  • Download URL: gbp_stack-1.9.0.tar.gz
  • Upload date:
  • Size: 27.9 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for gbp_stack-1.9.0.tar.gz
Algorithm Hash digest
SHA256 14c97fc6e5455bfd0d7f1c33372bb4dd0903443afa7b704062aa5bf44e41bad4
MD5 367e131b03ca72cb1dbe34fab9be24e3
BLAKE2b-256 efb33da569288f9bf632fe38d012914aa014fdbcb2e963e2b2cab18ad62c3737

See more details on using hashes here.

Provenance

The following attestation bundles were made for gbp_stack-1.9.0.tar.gz:

Publisher: release.yml on F000NKKK/Group-Protocol-Stack

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file gbp_stack-1.9.0-cp311-cp311-win_arm64.whl.

File metadata

  • Download URL: gbp_stack-1.9.0-cp311-cp311-win_arm64.whl
  • Upload date:
  • Size: 25.4 kB
  • Tags: CPython 3.11, Windows ARM64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for gbp_stack-1.9.0-cp311-cp311-win_arm64.whl
Algorithm Hash digest
SHA256 5b5ee4a5c76f24bb0ef8323887b45133d8c6d0b1bec06432aa76466a6efc8c65
MD5 d2c9e7cef2e338cd227643da5c9a34d1
BLAKE2b-256 a85969e125ad31bf4358e82dd46aac772e02318c140384f9bedb28be0fbe23f2

See more details on using hashes here.

Provenance

The following attestation bundles were made for gbp_stack-1.9.0-cp311-cp311-win_arm64.whl:

Publisher: release.yml on F000NKKK/Group-Protocol-Stack

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file gbp_stack-1.9.0-cp311-cp311-win_amd64.whl.

File metadata

  • Download URL: gbp_stack-1.9.0-cp311-cp311-win_amd64.whl
  • Upload date:
  • Size: 1.4 MB
  • Tags: CPython 3.11, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for gbp_stack-1.9.0-cp311-cp311-win_amd64.whl
Algorithm Hash digest
SHA256 852643fcb05c173630b174df1b743800de77598747953217d23de3bfd92b0b38
MD5 c48c6ce7e777e60d9095f8fb80f12c97
BLAKE2b-256 6f96ec8e8263db34c8081883395c0e85d5698fb59d1552bd2f8c735066992d55

See more details on using hashes here.

Provenance

The following attestation bundles were made for gbp_stack-1.9.0-cp311-cp311-win_amd64.whl:

Publisher: release.yml on F000NKKK/Group-Protocol-Stack

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file gbp_stack-1.9.0-cp311-cp311-manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for gbp_stack-1.9.0-cp311-cp311-manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 413d05aef2da5fb2a06cbed33d71f92b7eaac7ba9c922aa72468dcbdc2ae6337
MD5 3375dc0fc6ed5f23c8de7d4c4b09058c
BLAKE2b-256 7b401521876ac830bdf7b585a5ab00deee9a4f53ab9a22590547f0eb16582a1f

See more details on using hashes here.

Provenance

The following attestation bundles were made for gbp_stack-1.9.0-cp311-cp311-manylinux2014_x86_64.whl:

Publisher: release.yml on F000NKKK/Group-Protocol-Stack

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file gbp_stack-1.9.0-cp311-cp311-manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for gbp_stack-1.9.0-cp311-cp311-manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 1eff0aa4aac653da91221e553f808bad2923b50b9569b22926d5f63ea00f8fa1
MD5 557311069d0b656447226e42b67d8e29
BLAKE2b-256 b934094768d3f2b3a7715f8b7c041b929410881254730aa236584b5ed4a84e34

See more details on using hashes here.

Provenance

The following attestation bundles were made for gbp_stack-1.9.0-cp311-cp311-manylinux2014_aarch64.whl:

Publisher: release.yml on F000NKKK/Group-Protocol-Stack

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file gbp_stack-1.9.0-cp311-cp311-macosx_11_0_x86_64.whl.

File metadata

File hashes

Hashes for gbp_stack-1.9.0-cp311-cp311-macosx_11_0_x86_64.whl
Algorithm Hash digest
SHA256 abf8df5b60c6a9cb8b6b987e816963da32f0f9ce947697d6658f447154f8c1b7
MD5 6c8d8a1d5c08fbcff1ebc604b8b49883
BLAKE2b-256 c96f33f7826bc446f83e5878a774ea0faad21147522137e8a20166e022cb0361

See more details on using hashes here.

Provenance

The following attestation bundles were made for gbp_stack-1.9.0-cp311-cp311-macosx_11_0_x86_64.whl:

Publisher: release.yml on F000NKKK/Group-Protocol-Stack

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file gbp_stack-1.9.0-cp311-cp311-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for gbp_stack-1.9.0-cp311-cp311-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 5454d01fca3d6725e3b329d5228689944dc92fcbf43bf7a8ed8e967964846921
MD5 5f1781312c5043e4a9909a8cf8f1c18f
BLAKE2b-256 82562818714f6c93901c6b8a2677d1a64a2a5ee674124145f3feaae2d70a925a

See more details on using hashes here.

Provenance

The following attestation bundles were made for gbp_stack-1.9.0-cp311-cp311-macosx_11_0_arm64.whl:

Publisher: release.yml on F000NKKK/Group-Protocol-Stack

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

Pre-release

1.9.2rc2

7 files

Pre-release

1.9.2rc1

7 files

1.9.1

7 files

This release

1.9.0 This release

7 files

1.8.2

7 files

1.8.1

7 files

1.8.0

7 files

1.7.0

7 files

1.6.0

7 files

1.5.5

7 files

1.5.4

7 files

1.5.3

7 files

1.5.2

7 files

1.5.1

7 files

1.5.0

7 files

1.4.2

7 files

1.4.1

7 files

1.4.0

7 files

1.3.0

7 files

1.2.3

7 files

1.2.2

7 files

1.2.1

7 files

1.2.0

7 files

1.1.4

7 files

1.1.3

7 files

1.1.2

7 files

1.1.1

7 files

1.1.0

7 files

1.0.1

7 files

1.0.0

7 files

Pre-release

1.0.0rc4

7 files

Pre-release

1.0.0rc3

7 files

Pre-release

1.0.0rc1

7 files

0.2.0

7 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page