offline-protocol-sdk 0.28.0__py3-none-win_amd64.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- offline_protocol_sdk/__init__.py +22 -0
- offline_protocol_sdk/_callback_reentrancy.py +64 -0
- offline_protocol_sdk/address_declaration.py +207 -0
- offline_protocol_sdk/ble_manager.py +595 -0
- offline_protocol_sdk/ble_peripheral.py +673 -0
- offline_protocol_sdk/dnssd_bridge.py +614 -0
- offline_protocol_sdk/gateway_attach_policy.py +437 -0
- offline_protocol_sdk/gateway_manager.py +1217 -0
- offline_protocol_sdk/gateway_verdict_tracker.py +97 -0
- offline_protocol_sdk/internet_manager.py +1444 -0
- offline_protocol_sdk/legacy_store_adoption.py +184 -0
- offline_protocol_sdk/local_api/__init__.py +34 -0
- offline_protocol_sdk/local_api/authz.py +180 -0
- offline_protocol_sdk/local_api/cli.py +171 -0
- offline_protocol_sdk/local_api/codec.py +210 -0
- offline_protocol_sdk/local_api/dispatch.py +537 -0
- offline_protocol_sdk/local_api/mux.py +239 -0
- offline_protocol_sdk/local_api/server.py +546 -0
- offline_protocol_sdk/local_api/session.py +86 -0
- offline_protocol_sdk/local_api/table.py +849 -0
- offline_protocol_sdk/offline_protocol.py +13508 -0
- offline_protocol_sdk/peer_stream_manager.py +1303 -0
- offline_protocol_sdk/presence_watch_policy.py +102 -0
- offline_protocol_sdk/protocol_manager.py +1108 -0
- offline_protocol_sdk/relay_answer_prefixes.py +61 -0
- offline_protocol_sdk/secure_storage.py +551 -0
- offline_protocol_sdk/services.py +195 -0
- offline_protocol_sdk/state_storage.py +452 -0
- offline_protocol_sdk/storage_namespace.py +33 -0
- offline_protocol_sdk/transport_manager.py +138 -0
- offline_protocol_sdk/uniffi.dll +0 -0
- offline_protocol_sdk-0.28.0.dist-info/METADATA +519 -0
- offline_protocol_sdk-0.28.0.dist-info/RECORD +40 -0
- offline_protocol_sdk-0.28.0.dist-info/WHEEL +5 -0
- offline_protocol_sdk-0.28.0.dist-info/entry_points.txt +2 -0
- offline_protocol_sdk-0.28.0.dist-info/licenses/EXPORT.md +68 -0
- offline_protocol_sdk-0.28.0.dist-info/licenses/LICENSE +661 -0
- offline_protocol_sdk-0.28.0.dist-info/licenses/LICENSE-COMMERCIAL.md +89 -0
- offline_protocol_sdk-0.28.0.dist-info/licenses/THIRD-PARTY-NOTICES.md +6645 -0
- offline_protocol_sdk-0.28.0.dist-info/top_level.txt +1 -0
|
@@ -0,0 +1,138 @@
|
|
|
1
|
+
"""Base transport manager abstraction.
|
|
2
|
+
|
|
3
|
+
Mirrors the iOS ``TransportManager`` protocol and Android
|
|
4
|
+
``TransportManager`` interface so that each transport (BLE, Internet, etc.)
|
|
5
|
+
follows the same lifecycle contract.
|
|
6
|
+
"""
|
|
7
|
+
|
|
8
|
+
from __future__ import annotations
|
|
9
|
+
|
|
10
|
+
import logging
|
|
11
|
+
from abc import ABC, abstractmethod
|
|
12
|
+
from enum import Enum
|
|
13
|
+
from typing import Any, Callable
|
|
14
|
+
|
|
15
|
+
logger = logging.getLogger(__name__)
|
|
16
|
+
|
|
17
|
+
|
|
18
|
+
class TransportState(Enum):
|
|
19
|
+
"""Transport lifecycle states."""
|
|
20
|
+
|
|
21
|
+
UNAVAILABLE = "unavailable"
|
|
22
|
+
AVAILABLE = "available"
|
|
23
|
+
STARTING = "starting"
|
|
24
|
+
RUNNING = "running"
|
|
25
|
+
STOPPING = "stopping"
|
|
26
|
+
STOPPED = "stopped"
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
class TransportError(Exception):
|
|
30
|
+
"""Base error for transport operations."""
|
|
31
|
+
|
|
32
|
+
|
|
33
|
+
class TransportManager(ABC):
|
|
34
|
+
"""Abstract base for all transport implementations.
|
|
35
|
+
|
|
36
|
+
Subclasses must implement :meth:`is_available`, :meth:`start`, and
|
|
37
|
+
:meth:`stop`. Optional hooks :meth:`pause`, :meth:`resume`, and
|
|
38
|
+
:meth:`get_metrics` have sensible defaults.
|
|
39
|
+
"""
|
|
40
|
+
|
|
41
|
+
transport_id: str
|
|
42
|
+
transport_name: str
|
|
43
|
+
|
|
44
|
+
def __init__(self) -> None:
|
|
45
|
+
self._state = TransportState.STOPPED
|
|
46
|
+
self._on_state_change: Callable[[TransportState], None] | None = None
|
|
47
|
+
self._on_error: Callable[[Exception], None] | None = None
|
|
48
|
+
self._on_diagnostic: (
|
|
49
|
+
Callable[[str, str, dict[str, Any]], None] | None
|
|
50
|
+
) = None
|
|
51
|
+
|
|
52
|
+
@property
|
|
53
|
+
def state(self) -> TransportState:
|
|
54
|
+
return self._state
|
|
55
|
+
|
|
56
|
+
def set_delegate(
|
|
57
|
+
self,
|
|
58
|
+
*,
|
|
59
|
+
on_state_change: Callable[[TransportState], None] | None = None,
|
|
60
|
+
on_error: Callable[[Exception], None] | None = None,
|
|
61
|
+
on_diagnostic: (
|
|
62
|
+
Callable[[str, str, dict[str, Any]], None] | None
|
|
63
|
+
) = None,
|
|
64
|
+
) -> None:
|
|
65
|
+
"""Set delegate callbacks (equivalent to iOS TransportManagerDelegate)."""
|
|
66
|
+
self._on_state_change = on_state_change
|
|
67
|
+
self._on_error = on_error
|
|
68
|
+
self._on_diagnostic = on_diagnostic
|
|
69
|
+
|
|
70
|
+
@abstractmethod
|
|
71
|
+
def is_available(self) -> bool:
|
|
72
|
+
"""Return True if transport hardware/capabilities are available."""
|
|
73
|
+
...
|
|
74
|
+
|
|
75
|
+
@abstractmethod
|
|
76
|
+
async def start(self) -> None:
|
|
77
|
+
"""Start the transport. Raises :class:`TransportError` on failure."""
|
|
78
|
+
...
|
|
79
|
+
|
|
80
|
+
@abstractmethod
|
|
81
|
+
async def stop(self) -> None:
|
|
82
|
+
"""Stop the transport gracefully."""
|
|
83
|
+
...
|
|
84
|
+
|
|
85
|
+
async def pause(self) -> None:
|
|
86
|
+
"""Pause the transport (default: stop)."""
|
|
87
|
+
await self.stop()
|
|
88
|
+
|
|
89
|
+
async def resume(self) -> None:
|
|
90
|
+
"""Resume the transport from paused state (default: start)."""
|
|
91
|
+
await self.start()
|
|
92
|
+
|
|
93
|
+
def get_metrics(self) -> dict[str, Any]:
|
|
94
|
+
"""Return current transport metrics."""
|
|
95
|
+
return {}
|
|
96
|
+
|
|
97
|
+
# -- helpers for subclasses ------------------------------------------------
|
|
98
|
+
|
|
99
|
+
def _update_state(self, new_state: TransportState) -> None:
|
|
100
|
+
old = self._state
|
|
101
|
+
self._state = new_state
|
|
102
|
+
if old != new_state:
|
|
103
|
+
logger.debug(
|
|
104
|
+
"%s state: %s -> %s",
|
|
105
|
+
self.transport_id,
|
|
106
|
+
old.value,
|
|
107
|
+
new_state.value,
|
|
108
|
+
)
|
|
109
|
+
if self._on_state_change is not None:
|
|
110
|
+
self._on_state_change(new_state)
|
|
111
|
+
|
|
112
|
+
def _emit_error(self, exc: Exception) -> None:
|
|
113
|
+
logger.error("%s error: %s", self.transport_id, exc)
|
|
114
|
+
if self._on_error is not None:
|
|
115
|
+
self._on_error(exc)
|
|
116
|
+
|
|
117
|
+
def _emit_diagnostic(
|
|
118
|
+
self, level: str, message: str, context: dict[str, Any] | None = None
|
|
119
|
+
) -> None:
|
|
120
|
+
ctx = context or {}
|
|
121
|
+
logger.log(
|
|
122
|
+
_LOG_LEVELS.get(level, logging.DEBUG),
|
|
123
|
+
"%s: %s %s",
|
|
124
|
+
self.transport_id,
|
|
125
|
+
message,
|
|
126
|
+
ctx if ctx else "",
|
|
127
|
+
)
|
|
128
|
+
if self._on_diagnostic is not None:
|
|
129
|
+
self._on_diagnostic(level, message, ctx)
|
|
130
|
+
|
|
131
|
+
|
|
132
|
+
_LOG_LEVELS: dict[str, int] = {
|
|
133
|
+
"error": logging.ERROR,
|
|
134
|
+
"warning": logging.WARNING,
|
|
135
|
+
"warn": logging.WARNING,
|
|
136
|
+
"info": logging.INFO,
|
|
137
|
+
"debug": logging.DEBUG,
|
|
138
|
+
}
|
|
Binary file
|
|
@@ -0,0 +1,519 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: offline-protocol-sdk
|
|
3
|
+
Version: 0.28.0
|
|
4
|
+
Summary: Python bindings for the Offline Protocol SDK — offline-first mesh networking with MLS encryption
|
|
5
|
+
Author: Offline Protocol, Inc.
|
|
6
|
+
License-Expression: AGPL-3.0-only
|
|
7
|
+
Project-URL: Homepage, https://github.com/Offline-Protocol/offline-protocol-sdk
|
|
8
|
+
Project-URL: Repository, https://github.com/Offline-Protocol/offline-protocol-sdk
|
|
9
|
+
Project-URL: Issues, https://github.com/Offline-Protocol/offline-protocol-sdk/issues
|
|
10
|
+
Keywords: offline,messaging,p2p,mesh,ble,mls,encryption
|
|
11
|
+
Classifier: Development Status :: 4 - Beta
|
|
12
|
+
Classifier: Intended Audience :: Developers
|
|
13
|
+
Classifier: Programming Language :: Python :: 3
|
|
14
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
18
|
+
Classifier: Programming Language :: Rust
|
|
19
|
+
Classifier: Topic :: Communications
|
|
20
|
+
Classifier: Topic :: Security :: Cryptography
|
|
21
|
+
Requires-Python: >=3.10
|
|
22
|
+
Description-Content-Type: text/markdown
|
|
23
|
+
License-File: LICENSE
|
|
24
|
+
License-File: LICENSE-COMMERCIAL.md
|
|
25
|
+
License-File: THIRD-PARTY-NOTICES.md
|
|
26
|
+
License-File: EXPORT.md
|
|
27
|
+
Requires-Dist: bleak<4,>=1.1.1
|
|
28
|
+
Requires-Dist: bless<1.0,>=0.3; sys_platform != "win32"
|
|
29
|
+
Requires-Dist: websockets<17.0,>=12.0
|
|
30
|
+
Requires-Dist: keyring<26.0,>=25.0
|
|
31
|
+
Provides-Extra: dev
|
|
32
|
+
Requires-Dist: pytest>=7.0; extra == "dev"
|
|
33
|
+
Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
|
|
34
|
+
Requires-Dist: pip-audit>=2.7; extra == "dev"
|
|
35
|
+
Requires-Dist: zeroconf<0.160,>=0.140; extra == "dev"
|
|
36
|
+
Provides-Extra: lan
|
|
37
|
+
Requires-Dist: zeroconf<0.160,>=0.140; extra == "lan"
|
|
38
|
+
Requires-Dist: ifaddr<1,>=0.2; extra == "lan"
|
|
39
|
+
Dynamic: license-file
|
|
40
|
+
|
|
41
|
+
# Offline Protocol SDK — Python
|
|
42
|
+
|
|
43
|
+
Python bindings for the Offline Protocol SDK: offline-first mesh networking with MLS end-to-end encryption. Supports macOS, Linux, and Windows.
|
|
44
|
+
|
|
45
|
+
**Dual-licensed:** use it under [AGPL-3.0-only](https://github.com/Offline-Protocol/offline-protocol-sdk/blob/main/LICENSE), or buy a [commercial license](https://github.com/Offline-Protocol/offline-protocol-sdk/blob/main/LICENSE-COMMERCIAL.md), your call. The package metadata can only name `AGPL-3.0-only` because SPDX has no identifier for the commercial offer — see [License](#license) for the full breakdown.
|
|
46
|
+
|
|
47
|
+
> **Upgrading an existing install?** Read [docs/UPGRADING.md](https://github.com/Offline-Protocol/offline-protocol-sdk/blob/main/docs/UPGRADING.md)
|
|
48
|
+
> first — `ProtocolManager` now requires an explicit `state_root`, and this
|
|
49
|
+
> release is not safely downgradable.
|
|
50
|
+
|
|
51
|
+
## Quick Start
|
|
52
|
+
|
|
53
|
+
### 1. Build the native library
|
|
54
|
+
|
|
55
|
+
```bash
|
|
56
|
+
cd bindings/python
|
|
57
|
+
bash scripts/build-desktop.sh
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
This compiles the Rust core for your platform and generates the FFI bindings. It
|
|
61
|
+
regenerates Swift and Kotlin alongside Python by delegating to the repo-root
|
|
62
|
+
`scripts/generate-bindings.sh` — the three are one artifact set off one UDL, so
|
|
63
|
+
they are never refreshed apart.
|
|
64
|
+
|
|
65
|
+
**Prerequisites:** Rust toolchain, `uniffi-bindgen` (`cargo install uniffi --version 0.30.0 --features cli --locked`).
|
|
66
|
+
|
|
67
|
+
### 2. Install the package
|
|
68
|
+
|
|
69
|
+
```bash
|
|
70
|
+
pip install -e .
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
### 3. Use it
|
|
74
|
+
|
|
75
|
+
```python
|
|
76
|
+
import asyncio
|
|
77
|
+
from pathlib import Path
|
|
78
|
+
|
|
79
|
+
from offline_protocol_sdk import ProtocolManager
|
|
80
|
+
from offline_protocol_sdk.offline_protocol import ProtocolConfig, OverflowPolicy
|
|
81
|
+
|
|
82
|
+
config = ProtocolConfig(
|
|
83
|
+
app_id="my-app",
|
|
84
|
+
user_id="alice",
|
|
85
|
+
ble_enabled=False,
|
|
86
|
+
wifi_direct_enabled=False,
|
|
87
|
+
internet_enabled=True,
|
|
88
|
+
reticulum_enabled=False,
|
|
89
|
+
nostr_enabled=False,
|
|
90
|
+
prefer_online=True,
|
|
91
|
+
initial_ttl=3,
|
|
92
|
+
encryption_enabled=True,
|
|
93
|
+
auto_key_exchange=True,
|
|
94
|
+
store_pending=True,
|
|
95
|
+
require_encryption=False,
|
|
96
|
+
max_pending_per_peer=100,
|
|
97
|
+
max_pending_global=1000,
|
|
98
|
+
pending_ttl_ms=86_400_000, # 24 h (the SDK default)
|
|
99
|
+
overflow_policy=OverflowPolicy.DROP_OLDEST,
|
|
100
|
+
)
|
|
101
|
+
|
|
102
|
+
async def main():
|
|
103
|
+
# The installer must remove this application-owned directory on uninstall.
|
|
104
|
+
state_root = Path("/app/install-owned-data/offline-protocol")
|
|
105
|
+
async with ProtocolManager(
|
|
106
|
+
config,
|
|
107
|
+
event_handler=print,
|
|
108
|
+
state_root=state_root,
|
|
109
|
+
) as pm:
|
|
110
|
+
pm.internet.configure(server_url="ws://relay.example.com")
|
|
111
|
+
await pm.internet.start()
|
|
112
|
+
|
|
113
|
+
msg_id = pm.send_message("bob", "Hello from Python!")
|
|
114
|
+
print(f"Sent: {msg_id}")
|
|
115
|
+
|
|
116
|
+
# Keep running to receive messages
|
|
117
|
+
await asyncio.sleep(30)
|
|
118
|
+
|
|
119
|
+
asyncio.run(main())
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
### Two hosts without a relay
|
|
123
|
+
|
|
124
|
+
Set `wifi_direct_enabled=True` and `ProtocolManager` builds a
|
|
125
|
+
`PeerStreamManager` as `pm.peer_stream`. Configure and start it after
|
|
126
|
+
`pm.start()`, once this device has an address to prove:
|
|
127
|
+
|
|
128
|
+
```python
|
|
129
|
+
pm.peer_stream.configure(
|
|
130
|
+
listen_host="0.0.0.0", # every interface; the default
|
|
131
|
+
listen_port=7878, # 0 = ephemeral, None = connect out only
|
|
132
|
+
peers=["off1...@10.0.0.7:7878"], # or plain "host:port"; the address is then learned
|
|
133
|
+
advertise=True, discover=True, # DNS-SD, needs: pip install 'offline-protocol-sdk[lan]'
|
|
134
|
+
)
|
|
135
|
+
await pm.peer_stream.start()
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
A peer is announced only under the address its preamble proves, and
|
|
139
|
+
`pm.stop()` stops the stream layer with everything else.
|
|
140
|
+
|
|
141
|
+
### Services, and services on the LAN
|
|
142
|
+
|
|
143
|
+
`Services` wraps the generated `MeshServices` and keeps the one thing the
|
|
144
|
+
engine cannot give back: the list of what this node registered. `respond`
|
|
145
|
+
refuses a status the engine would refuse (`ok`, `not_found` and `error` are
|
|
146
|
+
the whole set) with the reason instead of an opaque core error.
|
|
147
|
+
|
|
148
|
+
```python
|
|
149
|
+
from offline_protocol_sdk.services import Services
|
|
150
|
+
from offline_protocol_sdk.dnssd_bridge import DnsSdBridge
|
|
151
|
+
|
|
152
|
+
services = Services(pm.protocol)
|
|
153
|
+
services.register("weather.v1", "2.0", {"format": "json"}) # before or after pm.start()
|
|
154
|
+
|
|
155
|
+
# Publish this node's registrations on the LAN and import the neighbours'.
|
|
156
|
+
# Needs: pip install 'offline-protocol-sdk[lan]'
|
|
157
|
+
bridge = DnsSdBridge(services, on_event=handle_event)
|
|
158
|
+
await bridge.start(address=pm.local_address, port=pm.peer_stream.listen_port)
|
|
159
|
+
...
|
|
160
|
+
await bridge.stop() # before pm.stop()
|
|
161
|
+
```
|
|
162
|
+
|
|
163
|
+
A LAN import arrives at `handle_event` as a `service_discovered` event with
|
|
164
|
+
`source: "lan"` and is kept in `bridge.lan_services()`; it is an unsigned
|
|
165
|
+
claim by whoever answered on the segment, never a discovery, and the bridge
|
|
166
|
+
never registers it with the engine. Registrations that do not fit the record
|
|
167
|
+
(a service id over 200 bytes, a capability key DNS-SD cannot carry, a record
|
|
168
|
+
over 1300 bytes) are kept on the mesh and not published, with a warning. The
|
|
169
|
+
mapping is [docs/spec/dns-sd-mapping.md](../../docs/spec/dns-sd-mapping.md).
|
|
170
|
+
|
|
171
|
+
## Architecture
|
|
172
|
+
|
|
173
|
+
```
|
|
174
|
+
offline_protocol_sdk/
|
|
175
|
+
├── offline_protocol.py # Auto-generated UniFFI bindings (DO NOT EDIT)
|
|
176
|
+
├── protocol_manager.py # High-level wrapper (processing loop, lifecycle)
|
|
177
|
+
├── internet_manager.py # WebSocket transport (websockets library)
|
|
178
|
+
├── peer_stream_manager.py # TCP peer streams + DNS-SD (the wifi_direct slot)
|
|
179
|
+
├── gateway_manager.py # Gateway-daemon client over TCP (the reticulum slot)
|
|
180
|
+
├── gateway_attach_policy.py # Its decisions and frame shapes, socket-free
|
|
181
|
+
├── gateway_verdict_tracker.py, presence_watch_policy.py
|
|
182
|
+
├── services.py # Service registry wrappers with the copy the engine lacks
|
|
183
|
+
├── dnssd_bridge.py # Services on the LAN: publish own, import neighbours' (optional extra `lan`)
|
|
184
|
+
├── ble_manager.py # BLE transport (bleak library)
|
|
185
|
+
├── secure_storage.py # MLS key storage (keyring library)
|
|
186
|
+
├── state_storage.py # Restartable protocol state (application data)
|
|
187
|
+
└── transport_manager.py # Base transport abstraction
|
|
188
|
+
```
|
|
189
|
+
|
|
190
|
+
### Transport Managers
|
|
191
|
+
|
|
192
|
+
| Transport | Library | Platforms | Notes |
|
|
193
|
+
|-----------|---------|-----------|-------|
|
|
194
|
+
| Internet/WebSocket | `websockets` | All | Primary transport for desktop |
|
|
195
|
+
| BLE | `bleak` | All | Central (scanner) role only; peripheral/GATT server requires `bless` |
|
|
196
|
+
| Peer stream (the `wifi_direct` slot) | `asyncio` sockets; `zeroconf` for LAN discovery (optional extra `lan`) | All | `PeerStreamManager`: TCP streams to configured `host:port` peers or hosts found over DNS-SD, each proved by the identity-assertion preamble ([spec](../../docs/spec/stream-framing.md)). Start it after `ProtocolManager.start()`; binds every interface unless `listen_host` narrows it |
|
|
197
|
+
| Reticulum (a gateway daemon) | `asyncio` sockets | All | `GatewayManager` as `pm.gateway` when `reticulum_enabled=True`: the [gateway-daemon contract](../../docs/spec/gateway-contract.md) over TCP to a daemon on local IP (`configure(daemon_address="localhost:4242")`, then `await pm.gateway.start()` after `pm.start()`). Attaches with a signed address declaration, settles each send on the gateway's verdict, watches presence. What answers is a daemon built to the contract; this package ships the device half. Apps driving the slot themselves replace the callback via `protocol.set_reticulum_transport_callback(...)` |
|
|
198
|
+
| Nostr | Built-in | All | Handled in Rust core (BIP-340 signing); `ProtocolManager` wires a stub callback when `nostr_enabled=True` — apps driving Nostr themselves replace it via `protocol.set_nostr_transport_callback(...)` |
|
|
199
|
+
|
|
200
|
+
### Secure Storage
|
|
201
|
+
|
|
202
|
+
MLS cryptographic key material is stored using the `keyring` library:
|
|
203
|
+
|
|
204
|
+
| Platform | Backend |
|
|
205
|
+
|----------|---------|
|
|
206
|
+
| macOS | Keychain |
|
|
207
|
+
| Linux | Secret Service (GNOME Keyring / KWallet) |
|
|
208
|
+
| Windows | Windows Credential Locker |
|
|
209
|
+
|
|
210
|
+
On a host with none of those available, `keyring` falls back to its failing
|
|
211
|
+
backend (every call raises), or to a plaintext one if `keyrings.alt` is
|
|
212
|
+
installed. `SecureStorage` logs a warning when it detects either, but it
|
|
213
|
+
does not refuse to run, and on Python that warning is louder than it looks.
|
|
214
|
+
The credential store also holds `protocol_state_record_key`, the per-install key
|
|
215
|
+
that seals pending messages, outbox entries, and media descriptors before they
|
|
216
|
+
reach `AppStateStorage`. On a plaintext backend that key sits in a readable
|
|
217
|
+
file, so the sealing gives you separation of *lifecycle* but not of
|
|
218
|
+
*confidentiality*: anyone who can read the credential store can open every
|
|
219
|
+
sealed protocol-state record. Install a real secret service (gnome-keyring,
|
|
220
|
+
kwallet) for any deployment where that matters, supply your own
|
|
221
|
+
`MlsStorageProvider`, or use the built-in file stores below.
|
|
222
|
+
|
|
223
|
+
### Run as a service: the local API
|
|
224
|
+
|
|
225
|
+
One process can own the engine and serve several local applications at once,
|
|
226
|
+
over JSON-RPC 2.0 on a WebSocket. The contract is
|
|
227
|
+
[the local API chapter](../../docs/spec/local-api.md); the reference server
|
|
228
|
+
ships in this package as `offline_protocol_sdk.local_api` and as the
|
|
229
|
+
`offline-protocol-service` command:
|
|
230
|
+
|
|
231
|
+
```bash
|
|
232
|
+
export OFFLINE_PROTOCOL_STORE_KEY="$(openssl rand -hex 32)" # once; keep it
|
|
233
|
+
offline-protocol-service --config config.json \
|
|
234
|
+
--mls-root /var/lib/example/keys --state-root /var/lib/example/state \
|
|
235
|
+
--socket /run/example/api.sock --listen 0.0.0.0:7878 --peer 10.0.0.2:7878
|
|
236
|
+
```
|
|
237
|
+
|
|
238
|
+
`config.json` holds the `ProtocolConfig` fields by name; the socket is
|
|
239
|
+
created owner-only. A client opens the socket, sends `hello` with its
|
|
240
|
+
application id, and calls the engine's own methods by name:
|
|
241
|
+
|
|
242
|
+
```python
|
|
243
|
+
import asyncio, json
|
|
244
|
+
from websockets.asyncio.client import unix_connect
|
|
245
|
+
|
|
246
|
+
async def main():
|
|
247
|
+
async with unix_connect("/run/example/api.sock", uri="ws://localhost/") as ws:
|
|
248
|
+
await ws.send(json.dumps({"jsonrpc": "2.0", "id": 1, "method": "hello",
|
|
249
|
+
"params": {"app_id": "notes"}}))
|
|
250
|
+
print(json.loads(await ws.recv())["result"]["local_address"])
|
|
251
|
+
|
|
252
|
+
asyncio.run(main())
|
|
253
|
+
```
|
|
254
|
+
|
|
255
|
+
Every message a `notes` client sends is stamped with that id, and a
|
|
256
|
+
`message_received` for `notes` reaches only `notes` clients; what the server
|
|
257
|
+
holds for an application whose client is away, and what it never puts on the
|
|
258
|
+
wire, is the chapter's. `--policy policy.json` adds the optional rules
|
|
259
|
+
(`spaces`, `denied`); `--tcp PORT --token-file PATH` serves loopback TCP with
|
|
260
|
+
a per-launch token instead of the socket. See
|
|
261
|
+
[the bridge contract](../../docs/bridges/local-api.md) for what the server
|
|
262
|
+
owes.
|
|
263
|
+
|
|
264
|
+
The guide is [docs/local-api.md](../../docs/local-api.md). Two clients ship
|
|
265
|
+
as examples and are run by the test suite against an in-process server:
|
|
266
|
+
[`examples/local_api_client.py`](examples/local_api_client.py) (this package's
|
|
267
|
+
`websockets` dependency, Unix socket or TCP) and
|
|
268
|
+
[`examples/local-api/client.mjs`](../../examples/local-api/client.mjs) at the
|
|
269
|
+
repository root (Node 22 or later, no dependencies, TCP with the token).
|
|
270
|
+
|
|
271
|
+
### Headless hosts: the built-in file stores
|
|
272
|
+
|
|
273
|
+
A server or container usually has no secret service at all. Pass a store key
|
|
274
|
+
and `ProtocolManager` uses the SDK's built-in file stores instead of
|
|
275
|
+
`SecureStorage` and `AppStateStorage`: every MLS record is sealed on disk under
|
|
276
|
+
that key, and protocol state is written in the same format `AppStateStorage`
|
|
277
|
+
writes.
|
|
278
|
+
|
|
279
|
+
```python
|
|
280
|
+
pm = ProtocolManager(
|
|
281
|
+
config,
|
|
282
|
+
store_key_env="OFFLINE_PROTOCOL_STORE_KEY", # 64 hex digits or base64
|
|
283
|
+
mls_root="/var/lib/example/keys", # or OFFLINE_PROTOCOL_MLS_ROOT
|
|
284
|
+
state_root="/var/lib/example/state", # or OFFLINE_PROTOCOL_STATE_ROOT
|
|
285
|
+
)
|
|
286
|
+
await pm.start()
|
|
287
|
+
```
|
|
288
|
+
|
|
289
|
+
- **The store key is 32 random bytes, generated once and kept.** Generate it
|
|
290
|
+
with `openssl rand -hex 32`, and hand it to the process the way the service
|
|
291
|
+
manager hands it any secret. Pass `store_key=<bytes>` instead if the host
|
|
292
|
+
already holds it. Never derive it from a password or a host name.
|
|
293
|
+
- **`mls_root` holds this device's identity.** It must survive an upgrade,
|
|
294
|
+
and losing it gives the device a new address. `state_root` is scoped to
|
|
295
|
+
the installation. Keep them apart: the same directory for both, or one
|
|
296
|
+
inside the other, is refused with `ProtocolError.InvalidArgument`. That
|
|
297
|
+
includes two spellings of one directory on a volume that folds case
|
|
298
|
+
(`keys` and `Keys` on macOS or Windows). That is found only once the
|
|
299
|
+
directory exists, so the refusal leaves the directory it created, with
|
|
300
|
+
no record written.
|
|
301
|
+
- **Moving an existing deployment onto the file stores starts a new
|
|
302
|
+
identity.** Nothing is carried over from the keyring: the device gets a
|
|
303
|
+
new address, and its sessions and queued messages stay with the old one.
|
|
304
|
+
Point `state_root` at a fresh directory. Both modes read
|
|
305
|
+
`OFFLINE_PROTOCOL_STATE_ROOT`, so a kept one is the easy mistake, and it
|
|
306
|
+
is refused with `ProtocolError.InvalidConfiguration`: the new identity
|
|
307
|
+
cannot unseal the old records, and the first restore would delete the
|
|
308
|
+
messages it could not read. The same refusal covers a lost `mls_root`
|
|
309
|
+
next to a surviving `state_root`, and it still applies after an attempt
|
|
310
|
+
that failed part-way. It also covers an `mls_root` that holds an
|
|
311
|
+
identity, but not the one that wrote the state: the first run over a pair
|
|
312
|
+
binds the two directories to each other, so a `state_root` put back after
|
|
313
|
+
a run over a fresh one is refused. A damaged key inside the store is not
|
|
314
|
+
refused, then or on any later start over the same `mls_root`: the SDK
|
|
315
|
+
replaces it and reports the
|
|
316
|
+
messages it lost as failed. A directory the process cannot read is
|
|
317
|
+
refused rather than taken for empty. No refusal changes or deletes a
|
|
318
|
+
record.
|
|
319
|
+
- **`start()` raises instead of starting without the identity.** A wrong key
|
|
320
|
+
raises `ProtocolError.InvalidConfiguration` and changes no record. A
|
|
321
|
+
`state_root` that cannot be created also raises it, after the MLS store
|
|
322
|
+
has created its own directory; fixing the root and retrying is safe. A
|
|
323
|
+
directory another process holds raises `ProtocolError.InvalidState`. The
|
|
324
|
+
keyring path logs its own initialisation failures and carries on; this one
|
|
325
|
+
does not, because an operator who supplied a key asked for the sealed store.
|
|
326
|
+
- **One manager per account directory, and `close()` gives the directory
|
|
327
|
+
up.** Each store holds a lock on its directory while open, in this
|
|
328
|
+
process or another. `await pm.close()` stops the manager and releases
|
|
329
|
+
both directories before it returns, whatever still refers to the manager
|
|
330
|
+
or to `pm.protocol`, so a new manager can open them at once. A closed
|
|
331
|
+
manager cannot be started again. Leaving
|
|
332
|
+
`async with ProtocolManager(...) as pm` closes it, so two blocks over the
|
|
333
|
+
same directories need nothing between them, and a block whose entry
|
|
334
|
+
failed closes what that entry had opened. `close()` raises
|
|
335
|
+
`ProtocolError.InvalidState` when the engine could not be stopped:
|
|
336
|
+
nothing was released, and the call can be repeated.
|
|
337
|
+
- **`stop()` keeps the directories, for a restart in place.** Call `stop()`
|
|
338
|
+
then `start()` on the same manager. A `stop()` or `close()` that was
|
|
339
|
+
cancelled or raised part-way can be called again to finish; a `close()`
|
|
340
|
+
cancelled while the core was already releasing the stores finishes by
|
|
341
|
+
itself a moment later. Do not rely
|
|
342
|
+
on dropping a stopped manager to release the directories: that happens
|
|
343
|
+
when the interpreter frees the core object, which a kept `pm.protocol`,
|
|
344
|
+
an event handler that refers back to the manager, or an exception whose
|
|
345
|
+
traceback names it can each put off. A `start()` that raises releases
|
|
346
|
+
the callbacks itself, whether the stores refused or the engine did; call
|
|
347
|
+
`close()` if the manager is not going to be started again.
|
|
348
|
+
- **A forked child holds the directories.** A child made with a bare
|
|
349
|
+
`os.fork()` while the stores are open inherits their locks and holds
|
|
350
|
+
them until it exits, whatever the parent closes; start subprocesses with
|
|
351
|
+
`subprocess` or the `spawn` method instead.
|
|
352
|
+
|
|
353
|
+
What the stores guarantee, and what a copied directory reveals, is in the
|
|
354
|
+
[MLS integration guide](../../docs/mls-integration.md#built-in-file-stores).
|
|
355
|
+
|
|
356
|
+
Restartable message-plane state is kept separately by `AppStateStorage`, outside
|
|
357
|
+
the credential store. The built-in stores derive an opaque account namespace
|
|
358
|
+
from both `app_id` and `user_id`, so multiple `ProtocolManager` instances do
|
|
359
|
+
not share keys, outboxes, or retry state.
|
|
360
|
+
|
|
361
|
+
Upgrading an install that predates namespacing keeps both halves of its state,
|
|
362
|
+
by two different mechanisms.
|
|
363
|
+
|
|
364
|
+
Its **MLS identity** is adopted by read-through: the first account to launch
|
|
365
|
+
claims the old, unscoped keyring service and inherits its identity, sessions,
|
|
366
|
+
and TOFU pins on demand. That service was shared by every account on the
|
|
367
|
+
install, so only one can inherit it — a second account starts from a fresh
|
|
368
|
+
identity and logs an error saying so. Inspect the outcome with
|
|
369
|
+
`SecureStorage(...).legacy_adoption`, or opt out with `adopt_legacy_store=False`.
|
|
370
|
+
|
|
371
|
+
Its **restartable delivery state** — outbox, pending queue, session and Welcome
|
|
372
|
+
lifecycles, peer key packages and capabilities, media descriptors, blocked
|
|
373
|
+
users, the Lamport clock — is swept out of the credential store into
|
|
374
|
+
`state_root` on the first launch of this release, and the credential-store copy
|
|
375
|
+
is deleted once the move is durable. The sweep is resumable and one-shot, and it
|
|
376
|
+
reads *through* the secure provider, so a `SecureStorage` built without a
|
|
377
|
+
namespace (which cannot claim the legacy service) finds nothing to sweep.
|
|
378
|
+
|
|
379
|
+
An account that loses the claim above gets neither: no identity *and* no
|
|
380
|
+
delivery state, so it comes up with an empty outbox and an empty block list,
|
|
381
|
+
every previously blocked peer unblocked.
|
|
382
|
+
|
|
383
|
+
Because the sweep deletes the credential-store copy, **downgrading is not a
|
|
384
|
+
rollback** — an older build reads the old location and finds none of it. Roll
|
|
385
|
+
forward, not back.
|
|
386
|
+
|
|
387
|
+
Python has no portable app container: `Application Support`, `LOCALAPPDATA`,
|
|
388
|
+
and XDG data directories commonly survive package removal. The SDK therefore
|
|
389
|
+
does not guess a persistent default. Pass `state_root=` or set
|
|
390
|
+
`OFFLINE_PROTOCOL_STATE_ROOT` to a directory owned by the installed
|
|
391
|
+
application, and make the installer remove that directory on uninstall:
|
|
392
|
+
|
|
393
|
+
```python
|
|
394
|
+
pm = ProtocolManager(
|
|
395
|
+
config,
|
|
396
|
+
state_root="/app/install-owned-data/offline-protocol",
|
|
397
|
+
)
|
|
398
|
+
```
|
|
399
|
+
|
|
400
|
+
Passing a custom `state_storage` bypasses `state_root`; the custom provider
|
|
401
|
+
then owns both account isolation and uninstall cleanup.
|
|
402
|
+
|
|
403
|
+
Custom integrations must provide both lifecycle-separated, account-isolated
|
|
404
|
+
interfaces:
|
|
405
|
+
|
|
406
|
+
```python
|
|
407
|
+
from offline_protocol_sdk.offline_protocol import (
|
|
408
|
+
MlsStorageProvider,
|
|
409
|
+
ProtocolStateStorageProvider,
|
|
410
|
+
)
|
|
411
|
+
|
|
412
|
+
class MySecureStorage(MlsStorageProvider):
|
|
413
|
+
def store(self, key_type: str, key_id: str, data: list[int]) -> None: ...
|
|
414
|
+
def load(self, key_type: str, key_id: str) -> list[int] | None: ...
|
|
415
|
+
def delete(self, key_type: str, key_id: str) -> None: ...
|
|
416
|
+
def list_keys(self, key_type: str) -> list[str]: ...
|
|
417
|
+
|
|
418
|
+
class MyStateStorage(ProtocolStateStorageProvider):
|
|
419
|
+
def store(self, key_type: str, key_id: str, data: bytes) -> None: ...
|
|
420
|
+
def load(self, key_type: str, key_id: str) -> bytes | None: ...
|
|
421
|
+
def delete(self, key_type: str, key_id: str) -> None: ...
|
|
422
|
+
def list_keys(self, key_type: str) -> list[str]: ...
|
|
423
|
+
|
|
424
|
+
pm = ProtocolManager(
|
|
425
|
+
config,
|
|
426
|
+
storage=MySecureStorage(),
|
|
427
|
+
state_storage=MyStateStorage(),
|
|
428
|
+
)
|
|
429
|
+
```
|
|
430
|
+
|
|
431
|
+
`ProtocolManager` keeps both callback objects alive for the protocol lifetime.
|
|
432
|
+
Protocol state must live in application data rather than Keychain, Secret
|
|
433
|
+
Service, or Windows Credential Locker. A custom provider shared by multiple
|
|
434
|
+
accounts must apply the same `(app_id, user_id)` isolation itself.
|
|
435
|
+
|
|
436
|
+
## Telemetry
|
|
437
|
+
|
|
438
|
+
Opt-in by key. Once `enable_telemetry` has the key and app id the developer
|
|
439
|
+
portal issued, the SDK collects, batches and uploads accepted events to the
|
|
440
|
+
Offline Protocol ingest on its own background thread; the host platform is
|
|
441
|
+
filled in from `platform`, and the batch queue is durable from the first
|
|
442
|
+
batch because `start()` attaches the state store before anything is emitted.
|
|
443
|
+
|
|
444
|
+
```python
|
|
445
|
+
pm = ProtocolManager(config)
|
|
446
|
+
await pm.start()
|
|
447
|
+
pm.enable_telemetry("mp_…", "app_…", app_version="1.4.2")
|
|
448
|
+
print(pm.telemetry_stats()) # sent, accepted, dropped, buffered, last error
|
|
449
|
+
pm.disable_telemetry() # final flush, then stop; stop() does this too
|
|
450
|
+
```
|
|
451
|
+
|
|
452
|
+
`flush_telemetry`, `end_telemetry_session`, `set_telemetry_enabled` and
|
|
453
|
+
`notify_app_state` complete the surface. What leaves the device, when, and how
|
|
454
|
+
to switch it off are in [docs/telemetry.md](../../docs/telemetry.md).
|
|
455
|
+
|
|
456
|
+
## Running the Example
|
|
457
|
+
|
|
458
|
+
```bash
|
|
459
|
+
# Terminal 1
|
|
460
|
+
python examples/basic_messaging.py --user alice --server ws://localhost:8080
|
|
461
|
+
|
|
462
|
+
# Terminal 2
|
|
463
|
+
python examples/basic_messaging.py --user bob --server ws://localhost:8080
|
|
464
|
+
```
|
|
465
|
+
|
|
466
|
+
## Development
|
|
467
|
+
|
|
468
|
+
```bash
|
|
469
|
+
# Install dev dependencies
|
|
470
|
+
pip install -e ".[dev]"
|
|
471
|
+
|
|
472
|
+
# Run tests
|
|
473
|
+
pytest tests/ -v
|
|
474
|
+
|
|
475
|
+
# Audit dependencies for CVEs
|
|
476
|
+
pip-audit --strict
|
|
477
|
+
```
|
|
478
|
+
|
|
479
|
+
## Platform Support
|
|
480
|
+
|
|
481
|
+
| Target | Architecture | Library |
|
|
482
|
+
|--------|-------------|---------|
|
|
483
|
+
| macOS | Apple Silicon (arm64) | `.dylib` |
|
|
484
|
+
| macOS | Intel (x86_64) | `.dylib` |
|
|
485
|
+
| Linux | x86_64 | `.so` |
|
|
486
|
+
| Linux | aarch64 | `.so` |
|
|
487
|
+
| Windows | x86_64 | `.dll` |
|
|
488
|
+
|
|
489
|
+
## License
|
|
490
|
+
|
|
491
|
+
Copyright © 2025-2026 Offline Protocol, Inc.
|
|
492
|
+
|
|
493
|
+
The Offline Protocol SDK is **dual-licensed**:
|
|
494
|
+
|
|
495
|
+
- **AGPL-3.0-only** — see [LICENSE](https://github.com/Offline-Protocol/offline-protocol-sdk/blob/main/LICENSE).
|
|
496
|
+
Free for use in projects that comply with AGPL-3.0, including its network-use
|
|
497
|
+
source-disclosure requirement (section 13).
|
|
498
|
+
- **Commercial License** — for proprietary applications that cannot or do not wish to
|
|
499
|
+
comply with the AGPL. See [LICENSE-COMMERCIAL.md](https://github.com/Offline-Protocol/offline-protocol-sdk/blob/main/LICENSE-COMMERCIAL.md)
|
|
500
|
+
(contact legal@offlineprotocol.com).
|
|
501
|
+
|
|
502
|
+
You may use the SDK under **either** license; you do not need both.
|
|
503
|
+
|
|
504
|
+
Both license texts, along with `THIRD-PARTY-NOTICES.md`, are also installed with the
|
|
505
|
+
package under `offline_protocol_sdk-<version>.dist-info/licenses/`. The links above are
|
|
506
|
+
absolute because this file is the PyPI long description, and PyPI does not resolve
|
|
507
|
+
repository-relative links.
|
|
508
|
+
|
|
509
|
+
### Optional dependencies
|
|
510
|
+
|
|
511
|
+
`THIRD-PARTY-NOTICES.md` covers the Rust crates compiled into the native
|
|
512
|
+
library. The `lan` extra (`pip install 'offline-protocol-sdk[lan]'`) adds two
|
|
513
|
+
runtime dependencies that pip installs from PyPI and that are never
|
|
514
|
+
redistributed in this wheel: [python-zeroconf](https://pypi.org/project/zeroconf/)
|
|
515
|
+
(LGPL-2.1-or-later), used by `peer_stream_manager.py` and `dnssd_bridge.py`
|
|
516
|
+
for DNS-SD, and [ifaddr](https://pypi.org/project/ifaddr/) (MIT), used to
|
|
517
|
+
list the interface addresses a record publishes. Both are imported only when a
|
|
518
|
+
manager or bridge is asked to advertise or discover; the base install imports
|
|
519
|
+
neither.
|