bitchat-protocol 0.1.0__tar.gz

bitchat_protocol-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,39 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+    tags: ['v*']
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.10', '3.11', '3.12']
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev]"
+      - run: pytest
+      - run: mypy bitchat_protocol
+
+  publish:
+    needs: test
+    runs-on: ubuntu-latest
+    if: startsWith(github.ref, 'refs/tags/v')
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - run: pip install hatch
+      - run: hatch build
+      - uses: pypa/gh-action-pypi-publish@release/v1

bitchat_protocol-0.1.0/.gitignore

@@ -0,0 +1,14 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+dist/
+build/
+.venv/
+venv/
+.pytest_cache/
+.mypy_cache/
+.benchmarks/
+*.whl
+*.tar.gz
+.DS_Store

bitchat_protocol-0.1.0/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog — bitchat_protocol (Python)
+
+All notable changes follow [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [0.1.0] — 2026-03-22
+
+Initial GA release.
+
+### Added
+- `encode(packet, padding=False)` / `decode(data)` — binary packet encode/decode; `decode` never raises
+- `BitchatPacket` dataclass: `version`, `type`, `ttl`, `timestamp`, `flags`, `sender_id`, `payload`
+- Protocol v1 (14-byte header) and v2 (16-byte header) support
+- Compression: raw deflate (wbits=-15) with 50,000:1 ratio safety cap; `IS_COMPRESSED` flag handling
+- `MessageType` enum with all wire-defined message types
+- TLV codec:
+  - `AnnouncementPacket(nickname, noise_public_key, signing_public_key)`
+  - `PrivateMessagePacket(message_id, content, recipient_id?, sender_id?, timestamp?)`
+  - `encode_announcement(pkt)` / `decode_announcement(data)` → `AnnouncementPacket | None`
+  - `encode_private_message(pkt)` / `decode_private_message(data)` → `PrivateMessagePacket | None`
+- `peer_id_from_noise_key(noise_public_key)` — derive 8-byte peer ID from 32-byte key
+- `peer_id_to_hex(peer_id)` / `peer_id_from_hex(hex_str)` — hex conversion helpers
+- Cross-language compatibility: wire format matches `@bitchat-sdk/protocol-core` (JS) and `BitchatProtocol` (Swift)
+- Comprehensive fuzz and stress test suite (38 tests)
+
+### Protocol Compatibility
+Wire-format compatible with BitChat iOS (Swift), BitChat Android (Kotlin), `@bitchat-sdk/protocol-core`, and `BitchatProtocol`.
+
+[0.1.0]: https://github.com/bitchat-sdk/protocol-core-py/releases/tag/v0.1.0
+
+[Unreleased]: https://github.com/bitchat-sdk/protocol-core-py/compare/v0.1.0...HEAD

bitchat_protocol-0.1.0/LICENSE

@@ -0,0 +1,24 @@
+This is free and unencumbered software released into the public domain.
+
+Anyone is free to copy, modify, publish, use, compile, sell, or
+distribute this software, either in source code form or as compiled
+binaries, for any purpose, commercial or non-commercial, and by any
+means.
+
+In jurisdictions that recognize copyright laws, the author or authors
+of this software dedicate any and all copyright interest in the
+software to the public domain. We make this dedication for the benefit
+of the public at large and to the detriment of our heirs and
+successors. We intend this dedication to be an overt act of
+relinquishment in perpetuity of all rights to the present and future
+work under copyright law.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
+
+For more information, please refer to <https://unlicense.org>

bitchat_protocol-0.1.0/PKG-INFO

@@ -0,0 +1,162 @@
+Metadata-Version: 2.4
+Name: bitchat-protocol
+Version: 0.1.0
+Summary: BitChat binary protocol encode/decode — packet structs, TLV codec, peer ID utilities
+Project-URL: Source Code, https://github.com/bitchat-sdk/protocol-core-py
+Project-URL: Bug Tracker, https://github.com/bitchat-sdk/protocol-core-py/issues
+Project-URL: Changelog, https://github.com/bitchat-sdk/protocol-core-py/blob/main/CHANGELOG.md
+Author: bitchat-sdk contributors
+License: Unlicense
+License-File: LICENSE
+Keywords: bitchat,ble,mesh,nostr,p2p,protocol
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: The Unlicense (Unlicense)
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Communications
+Classifier: Topic :: Security :: Cryptography
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: mypy>=1.9; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# bitchat-protocol
+
+BitChat binary protocol encode/decode for Python.
+
+Implements the wire format from the BitChat mesh networking protocol:
+binary packet encode/decode, TLV codec for announcement and private message
+structures, and peer ID derivation utilities.
+
+## Installation
+
+```bash
+pip install bitchat-protocol
+```
+
+Requires Python 3.10+.
+
+## Quick Start
+
+```python
+from bitchat_protocol import (
+    encode, decode,
+    BitchatPacket, MessageType,
+    encode_announcement, decode_announcement,
+    AnnouncementPacket,
+    peer_id_from_noise_key,
+)
+
+# Encode a broadcast message
+import time
+packet = BitchatPacket(
+    version=1,
+    type=int(MessageType.MESSAGE),
+    ttl=7,
+    timestamp=int(time.time() * 1000),
+    flags=0,
+    sender_id=bytes.fromhex('abcdef0123456789'),
+    payload='Hello, BitChat!'.encode(),
+)
+wire = encode(packet, padding=True)   # padded for BLE transmission
+
+# Decode from bytes received over BLE or Nostr relay
+decoded = decode(wire)
+if decoded:
+    print('type:', decoded.type)
+    print('payload:', decoded.payload.decode())
+```
+
+## API
+
+### Packet Encode/Decode
+
+```python
+encode(packet: BitchatPacket, *, padding: bool = False) -> bytes
+decode(data: bytes) -> BitchatPacket | None
+```
+
+`decode()` returns `None` (never raises) on invalid or truncated input.
+
+### TLV: AnnouncementPacket
+
+```python
+encode_announcement(packet: AnnouncementPacket) -> bytes
+decode_announcement(data: bytes) -> AnnouncementPacket | None
+```
+
+Decoder is **lenient**: unknown TLV tags are skipped (forward-compatible).
+
+### TLV: PrivateMessagePacket
+
+```python
+encode_private_message(packet: PrivateMessagePacket) -> bytes
+decode_private_message(data: bytes) -> PrivateMessagePacket | None
+```
+
+Decoder is **strict**: returns `None` on any unknown TLV tag.
+
+### Peer ID Utilities
+
+```python
+peer_id_from_noise_key(noise_public_key: bytes) -> str   # 16-char hex
+peer_id_to_bytes(peer_id: str) -> bytes                  # 8 bytes
+peer_id_from_bytes(data: bytes) -> str                   # 16-char hex
+nostr_geo_dm_peer_id(nostr_pubkey_hex: str) -> str       # "nostr_" + prefix
+nostr_geo_chat_peer_id(nostr_pubkey_hex: str) -> str     # "nostr:" + prefix
+```
+
+### Utilities
+
+```python
+hex_to_bytes(hex_str: str) -> bytes
+bytes_to_hex(data: bytes) -> str
+```
+
+## Wire Format
+
+### v1 Header (14 bytes)
+```
+[version:1][type:1][ttl:1][timestamp:8 BE uint64][flags:1][payloadLen:2 BE uint16]
+[senderID:8]
+[recipientID:8]         — if flags & HAS_RECIPIENT
+[payload:payloadLen]
+[signature:64]          — if flags & HAS_SIGNATURE
+```
+
+### v2 Header (16 bytes)
+Same but `payloadLen` is 4 bytes (BE uint32) and source routing is supported.
+
+### Flags Byte
+| Bit | Value | Name |
+|-----|-------|------|
+| 0 | 0x01 | HAS_RECIPIENT |
+| 1 | 0x02 | HAS_SIGNATURE |
+| 2 | 0x04 | IS_COMPRESSED |
+| 3 | 0x08 | HAS_ROUTE (v2+ only) |
+| 4 | 0x10 | IS_RSR |
+
+## Running Tests
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## Compatibility
+
+This package implements the same binary wire format as:
+- `ios/bitchat/Protocols/BinaryProtocol.swift`
+- `android/.../BinaryProtocol.kt`
+
+Cross-language compatibility is verified by the golden fixture suite in
+the [bitchat-sdk](https://github.com/bitchat-sdk) org.
+
+## License
+
+Unlicense — public domain.

bitchat_protocol-0.1.0/README.md

@@ -0,0 +1,135 @@
+# bitchat-protocol
+
+BitChat binary protocol encode/decode for Python.
+
+Implements the wire format from the BitChat mesh networking protocol:
+binary packet encode/decode, TLV codec for announcement and private message
+structures, and peer ID derivation utilities.
+
+## Installation
+
+```bash
+pip install bitchat-protocol
+```
+
+Requires Python 3.10+.
+
+## Quick Start
+
+```python
+from bitchat_protocol import (
+    encode, decode,
+    BitchatPacket, MessageType,
+    encode_announcement, decode_announcement,
+    AnnouncementPacket,
+    peer_id_from_noise_key,
+)
+
+# Encode a broadcast message
+import time
+packet = BitchatPacket(
+    version=1,
+    type=int(MessageType.MESSAGE),
+    ttl=7,
+    timestamp=int(time.time() * 1000),
+    flags=0,
+    sender_id=bytes.fromhex('abcdef0123456789'),
+    payload='Hello, BitChat!'.encode(),
+)
+wire = encode(packet, padding=True)   # padded for BLE transmission
+
+# Decode from bytes received over BLE or Nostr relay
+decoded = decode(wire)
+if decoded:
+    print('type:', decoded.type)
+    print('payload:', decoded.payload.decode())
+```
+
+## API
+
+### Packet Encode/Decode
+
+```python
+encode(packet: BitchatPacket, *, padding: bool = False) -> bytes
+decode(data: bytes) -> BitchatPacket | None
+```
+
+`decode()` returns `None` (never raises) on invalid or truncated input.
+
+### TLV: AnnouncementPacket
+
+```python
+encode_announcement(packet: AnnouncementPacket) -> bytes
+decode_announcement(data: bytes) -> AnnouncementPacket | None
+```
+
+Decoder is **lenient**: unknown TLV tags are skipped (forward-compatible).
+
+### TLV: PrivateMessagePacket
+
+```python
+encode_private_message(packet: PrivateMessagePacket) -> bytes
+decode_private_message(data: bytes) -> PrivateMessagePacket | None
+```
+
+Decoder is **strict**: returns `None` on any unknown TLV tag.
+
+### Peer ID Utilities
+
+```python
+peer_id_from_noise_key(noise_public_key: bytes) -> str   # 16-char hex
+peer_id_to_bytes(peer_id: str) -> bytes                  # 8 bytes
+peer_id_from_bytes(data: bytes) -> str                   # 16-char hex
+nostr_geo_dm_peer_id(nostr_pubkey_hex: str) -> str       # "nostr_" + prefix
+nostr_geo_chat_peer_id(nostr_pubkey_hex: str) -> str     # "nostr:" + prefix
+```
+
+### Utilities
+
+```python
+hex_to_bytes(hex_str: str) -> bytes
+bytes_to_hex(data: bytes) -> str
+```
+
+## Wire Format
+
+### v1 Header (14 bytes)
+```
+[version:1][type:1][ttl:1][timestamp:8 BE uint64][flags:1][payloadLen:2 BE uint16]
+[senderID:8]
+[recipientID:8]         — if flags & HAS_RECIPIENT
+[payload:payloadLen]
+[signature:64]          — if flags & HAS_SIGNATURE
+```
+
+### v2 Header (16 bytes)
+Same but `payloadLen` is 4 bytes (BE uint32) and source routing is supported.
+
+### Flags Byte
+| Bit | Value | Name |
+|-----|-------|------|
+| 0 | 0x01 | HAS_RECIPIENT |
+| 1 | 0x02 | HAS_SIGNATURE |
+| 2 | 0x04 | IS_COMPRESSED |
+| 3 | 0x08 | HAS_ROUTE (v2+ only) |
+| 4 | 0x10 | IS_RSR |
+
+## Running Tests
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## Compatibility
+
+This package implements the same binary wire format as:
+- `ios/bitchat/Protocols/BinaryProtocol.swift`
+- `android/.../BinaryProtocol.kt`
+
+Cross-language compatibility is verified by the golden fixture suite in
+the [bitchat-sdk](https://github.com/bitchat-sdk) org.
+
+## License
+
+Unlicense — public domain.

bitchat_protocol-0.1.0/bitchat_protocol/__init__.py

@@ -0,0 +1,86 @@
+"""
+bitchat_protocol — BitChat binary protocol encode/decode for Python.
+
+Quickstart:
+
+    from bitchat_protocol import encode, decode, MessageType, AnnouncementPacket, BitchatPacket
+
+    packet = BitchatPacket(
+        version=1, type=int(MessageType.MESSAGE), ttl=7,
+        timestamp=0, flags=0,
+        sender_id=bytes.fromhex('abcdef0123456789'),
+        payload=b'Hello, BitChat!',
+    )
+    wire = encode(packet)
+    decoded = decode(wire)
+"""
+
+from .types import (
+    MessageType,
+    NoisePayloadType,
+    PacketFlag,
+    BitchatPacket,
+    AnnouncementPacket,
+    PrivateMessagePacket,
+)
+from .errors import (
+    BitchatProtocolError,
+    PacketTooShortError,
+    UnsupportedVersionError,
+    TruncatedFieldError,
+    DecompressionError,
+    SuspiciousCompressionRatioError,
+    TLVDecodeError,
+    TLVEncodeError,
+)
+from .codec import encode, decode, hex_to_bytes, bytes_to_hex
+from .tlv import (
+    encode_announcement,
+    decode_announcement,
+    encode_private_message,
+    decode_private_message,
+)
+from .peer import (
+    peer_id_from_noise_key,
+    peer_id_to_bytes,
+    peer_id_from_bytes,
+    nostr_geo_dm_peer_id,
+    nostr_geo_chat_peer_id,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # Types
+    "MessageType",
+    "NoisePayloadType",
+    "PacketFlag",
+    "BitchatPacket",
+    "AnnouncementPacket",
+    "PrivateMessagePacket",
+    # Errors
+    "BitchatProtocolError",
+    "PacketTooShortError",
+    "UnsupportedVersionError",
+    "TruncatedFieldError",
+    "DecompressionError",
+    "SuspiciousCompressionRatioError",
+    "TLVDecodeError",
+    "TLVEncodeError",
+    # Codec
+    "encode",
+    "decode",
+    "hex_to_bytes",
+    "bytes_to_hex",
+    # TLV
+    "encode_announcement",
+    "decode_announcement",
+    "encode_private_message",
+    "decode_private_message",
+    # Peer
+    "peer_id_from_noise_key",
+    "peer_id_to_bytes",
+    "peer_id_from_bytes",
+    "nostr_geo_dm_peer_id",
+    "nostr_geo_chat_peer_id",
+]