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.
Files changed (40) hide show
  1. offline_protocol_sdk/__init__.py +22 -0
  2. offline_protocol_sdk/_callback_reentrancy.py +64 -0
  3. offline_protocol_sdk/address_declaration.py +207 -0
  4. offline_protocol_sdk/ble_manager.py +595 -0
  5. offline_protocol_sdk/ble_peripheral.py +673 -0
  6. offline_protocol_sdk/dnssd_bridge.py +614 -0
  7. offline_protocol_sdk/gateway_attach_policy.py +437 -0
  8. offline_protocol_sdk/gateway_manager.py +1217 -0
  9. offline_protocol_sdk/gateway_verdict_tracker.py +97 -0
  10. offline_protocol_sdk/internet_manager.py +1444 -0
  11. offline_protocol_sdk/legacy_store_adoption.py +184 -0
  12. offline_protocol_sdk/local_api/__init__.py +34 -0
  13. offline_protocol_sdk/local_api/authz.py +180 -0
  14. offline_protocol_sdk/local_api/cli.py +171 -0
  15. offline_protocol_sdk/local_api/codec.py +210 -0
  16. offline_protocol_sdk/local_api/dispatch.py +537 -0
  17. offline_protocol_sdk/local_api/mux.py +239 -0
  18. offline_protocol_sdk/local_api/server.py +546 -0
  19. offline_protocol_sdk/local_api/session.py +86 -0
  20. offline_protocol_sdk/local_api/table.py +849 -0
  21. offline_protocol_sdk/offline_protocol.py +13508 -0
  22. offline_protocol_sdk/peer_stream_manager.py +1303 -0
  23. offline_protocol_sdk/presence_watch_policy.py +102 -0
  24. offline_protocol_sdk/protocol_manager.py +1108 -0
  25. offline_protocol_sdk/relay_answer_prefixes.py +61 -0
  26. offline_protocol_sdk/secure_storage.py +551 -0
  27. offline_protocol_sdk/services.py +195 -0
  28. offline_protocol_sdk/state_storage.py +452 -0
  29. offline_protocol_sdk/storage_namespace.py +33 -0
  30. offline_protocol_sdk/transport_manager.py +138 -0
  31. offline_protocol_sdk/uniffi.dll +0 -0
  32. offline_protocol_sdk-0.28.0.dist-info/METADATA +519 -0
  33. offline_protocol_sdk-0.28.0.dist-info/RECORD +40 -0
  34. offline_protocol_sdk-0.28.0.dist-info/WHEEL +5 -0
  35. offline_protocol_sdk-0.28.0.dist-info/entry_points.txt +2 -0
  36. offline_protocol_sdk-0.28.0.dist-info/licenses/EXPORT.md +68 -0
  37. offline_protocol_sdk-0.28.0.dist-info/licenses/LICENSE +661 -0
  38. offline_protocol_sdk-0.28.0.dist-info/licenses/LICENSE-COMMERCIAL.md +89 -0
  39. offline_protocol_sdk-0.28.0.dist-info/licenses/THIRD-PARTY-NOTICES.md +6645 -0
  40. 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.