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,195 @@
1
+ """Application-level service wrappers over the generated ``MeshServices``.
2
+
3
+ The engine keeps the registry of what this node offers, and it cannot list
4
+ it: the FFI has register, unregister, discover, request and respond, and no
5
+ enumeration. Anything that needs the list (a DNS-SD publisher, a status page,
6
+ a restart that re-announces) keeps a copy. This module keeps that copy once,
7
+ beside the calls that change it, so that the copy and the engine's registry
8
+ move together: the engine call runs first, and the copy changes only when
9
+ the engine accepted.
10
+
11
+ What is here is the mesh side only. A LAN import under
12
+ ``docs/spec/dns-sd-mapping.md`` is a claim by an unsigned record, and it is
13
+ never registered with the engine through this module or any other: that
14
+ would sign, under this node's identity, a claim made by whoever answered on
15
+ the segment (invariant 2 of the chapter). :class:`ServiceRecord` carries a
16
+ ``source`` so that a reader can tell the two apart, and only records with
17
+ ``source == "local"`` ever reach :meth:`Services.register`.
18
+
19
+ The response status set is closed. The engine accepts ``ok``, ``not_found``
20
+ and ``error``, refuses any other status on send, and drops a response with
21
+ any other status on receipt; a status the guide once called
22
+ "application-defined" is a response nobody receives. The set is mirrored
23
+ here as a literal, pinned by ``test_services.py`` the way the bridge rules
24
+ pin every hand-mirrored constant (C5), so that a respond that would be
25
+ refused fails here with the reason instead of as an opaque core error.
26
+ """
27
+
28
+ from __future__ import annotations
29
+
30
+ import logging
31
+ import threading
32
+ from dataclasses import dataclass, field
33
+ from typing import Any, Callable, Mapping, Protocol
34
+
35
+ from .offline_protocol import MeshServices, OfflineProtocol
36
+
37
+ logger = logging.getLogger(__name__)
38
+
39
+ #: The response statuses the engine accepts (``VALID_SERVICE_STATUSES`` in
40
+ #: the services crate). Mirrored as a literal; see the module docstring.
41
+ VALID_STATUSES: tuple[str, ...] = ("ok", "not_found", "error")
42
+
43
+ #: A registration this node made.
44
+ SOURCE_LOCAL = "local"
45
+ #: An import from an unsigned LAN record (``docs/spec/dns-sd-mapping.md``).
46
+ SOURCE_LAN = "lan"
47
+
48
+
49
+ @dataclass(frozen=True)
50
+ class ServiceRecord:
51
+ """One service, as this node offers it or as a LAN neighbour claims to.
52
+
53
+ ``provider`` is ``None`` for this node's own registrations and the
54
+ claimed address for a LAN import. ``capabilities`` is a copy: a caller
55
+ mutating its own map afterwards does not change what was registered.
56
+ """
57
+
58
+ service_id: str
59
+ version: str = ""
60
+ capabilities: Mapping[str, str] = field(default_factory=dict)
61
+ provider: str | None = None
62
+ source: str = SOURCE_LOCAL
63
+
64
+ def __post_init__(self) -> None:
65
+ object.__setattr__(self, "capabilities", dict(self.capabilities))
66
+
67
+ @property
68
+ def is_local(self) -> bool:
69
+ return self.source == SOURCE_LOCAL
70
+
71
+
72
+ class ServicesListener(Protocol):
73
+ """What a publisher (the DNS-SD bridge) hears from the registry.
74
+
75
+ Both are called outside the registry's lock, on the thread that made the
76
+ change, after the engine accepted it. A listener that raises is logged
77
+ and does not undo the registration: the mesh registration is the primary
78
+ and a LAN copy that could not be published is the LAN's loss only.
79
+ """
80
+
81
+ def on_registered(self, record: ServiceRecord) -> None: ...
82
+
83
+ def on_unregistered(self, record: ServiceRecord) -> None: ...
84
+
85
+
86
+ class Services:
87
+ """Register, unregister, discover, request and respond, with the copy of
88
+ this node's registrations the engine cannot provide.
89
+
90
+ Construct it over a live :class:`OfflineProtocol` (``pm.protocol``); the
91
+ generated :class:`MeshServices` is built here. The engine takes a
92
+ registration before ``start()`` as well as after, so a host may register
93
+ everything it offers before it starts.
94
+ """
95
+
96
+ def __init__(self, protocol: OfflineProtocol, *, mesh_services: Any | None = None) -> None:
97
+ self._mesh: Any = mesh_services if mesh_services is not None else MeshServices(protocol)
98
+ self._lock = threading.Lock()
99
+ self._local: dict[str, ServiceRecord] = {}
100
+ self._listeners: list[ServicesListener] = []
101
+
102
+ # -- the registry ---------------------------------------------------------
103
+
104
+ def register(
105
+ self,
106
+ service_id: str,
107
+ version: str = "",
108
+ capabilities: Mapping[str, str] | None = None,
109
+ ) -> ServiceRecord:
110
+ """Register a service this node offers.
111
+
112
+ Registering an id again replaces the descriptor, as the engine does;
113
+ listeners hear the old record unregistered and the new one registered.
114
+ Raises the core's error when the engine refuses the id (empty,
115
+ whitespace, over 256 bytes, or a reserved ``__`` prefix).
116
+ """
117
+ record = ServiceRecord(service_id, version, capabilities or {})
118
+ self._mesh.register_service(service_id, version, dict(record.capabilities))
119
+ with self._lock:
120
+ previous = self._local.get(service_id)
121
+ self._local[service_id] = record
122
+ listeners = list(self._listeners)
123
+ if previous is not None:
124
+ self._notify(listeners, "on_unregistered", previous)
125
+ self._notify(listeners, "on_registered", record)
126
+ return record
127
+
128
+ def unregister(self, service_id: str) -> bool:
129
+ """Unregister a service. Returns what the engine returns: whether it
130
+ was registered. The copy is kept in step with the engine's answer,
131
+ so an id the engine did not hold is not in the copy afterwards
132
+ either, whatever this side believed."""
133
+ found = bool(self._mesh.unregister_service(service_id))
134
+ with self._lock:
135
+ previous = self._local.pop(service_id, None)
136
+ listeners = list(self._listeners)
137
+ if previous is not None:
138
+ self._notify(listeners, "on_unregistered", previous)
139
+ return found
140
+
141
+ def registered(self) -> list[ServiceRecord]:
142
+ """This node's registrations, in registration order."""
143
+ with self._lock:
144
+ return list(self._local.values())
145
+
146
+ def get(self, service_id: str) -> ServiceRecord | None:
147
+ with self._lock:
148
+ return self._local.get(service_id)
149
+
150
+ # -- the calls that carry no state -----------------------------------------
151
+
152
+ def discover(self, service_id: str | None = None) -> str:
153
+ """Broadcast a discovery query; returns the query id the
154
+ ``service_discovered`` events will carry."""
155
+ return str(self._mesh.discover_services(service_id))
156
+
157
+ def request(self, provider: str, service_id: str, method: str, body: str) -> str:
158
+ """Send a request to a provider; returns the request id the
159
+ ``service_response_received`` event will carry."""
160
+ return str(self._mesh.send_service_request(provider, service_id, method, body))
161
+
162
+ def respond(self, request_id: str, requester: str, service_id: str, status: str, body: str) -> str:
163
+ """Answer a ``service_request_received`` event.
164
+
165
+ ``status`` must be one of :data:`VALID_STATUSES`; the engine refuses
166
+ any other and the requester drops any other, so it is refused here
167
+ with the reason.
168
+ """
169
+ if status not in VALID_STATUSES:
170
+ raise ValueError(
171
+ f"status {status!r} is not one the engine sends or a requester keeps; "
172
+ f"use one of {', '.join(VALID_STATUSES)}"
173
+ )
174
+ return str(self._mesh.respond_to_service_request(request_id, requester, service_id, status, body))
175
+
176
+ # -- listeners ------------------------------------------------------------
177
+
178
+ def add_listener(self, listener: ServicesListener) -> None:
179
+ with self._lock:
180
+ if listener not in self._listeners:
181
+ self._listeners.append(listener)
182
+
183
+ def remove_listener(self, listener: ServicesListener) -> None:
184
+ with self._lock:
185
+ if listener in self._listeners:
186
+ self._listeners.remove(listener)
187
+
188
+ @staticmethod
189
+ def _notify(listeners: list[ServicesListener], method: str, record: ServiceRecord) -> None:
190
+ for listener in listeners:
191
+ callback: Callable[[ServiceRecord], None] = getattr(listener, method)
192
+ try:
193
+ callback(record)
194
+ except Exception:
195
+ logger.exception("service listener %r failed in %s", listener, method)
@@ -0,0 +1,452 @@
1
+ """File-backed storage for restartable protocol and message-plane state.
2
+
3
+ Values are opaque bytes and are written verbatim: the SDK seals the categories
4
+ that can carry message plaintext or media key material before handing them over,
5
+ so they arrive as ciphertext. Do not inspect, re-encode, or truncate them.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ import hashlib
11
+ import logging
12
+ import os
13
+ import tempfile
14
+ import threading
15
+ from pathlib import Path
16
+
17
+ from .offline_protocol import MlsStorageError, ProtocolStateStorageProvider
18
+ from .storage_namespace import require_account_storage_namespace
19
+
20
+ logger = logging.getLogger(__name__)
21
+
22
+ _STATE_ROOT_ENV = "OFFLINE_PROTOCOL_STATE_ROOT"
23
+
24
+ # -- on-disk record format ---------------------------------------------------
25
+ #
26
+ # Filenames are a fixed-length lowercase hex digest rather than an encoding of
27
+ # the key itself. An encoding cannot be a correct filesystem key: it is
28
+ # case-sensitive (so ``AAG`` and ``AAa`` name the same file on a
29
+ # case-insensitive volume, and one record silently overwrites the other) and its
30
+ # length grows with the key (so a long-but-valid protocol id overruns
31
+ # ``NAME_MAX``). A digest is fixed-length, lowercase, and collision-free in
32
+ # practice.
33
+ #
34
+ # Because a digest is one-way, the exact key cannot be recovered from the name,
35
+ # so each record carries it in a header instead. That also makes every file
36
+ # independently attributable and lets a read verify it opened the record it
37
+ # asked for.
38
+ #
39
+ # bytes 0..4 magic "OPS1"
40
+ # bytes 4..6 key_type length, big-endian u16
41
+ # bytes 6..8 key_id length, big-endian u16
42
+ # then key_type UTF-8, key_id UTF-8, value bytes
43
+ #
44
+ # Keep this format, its limits, and the golden vectors in
45
+ # ``tests/test_state_storage.py`` in sync with the iOS and Android providers.
46
+
47
+ RECORD_MAGIC = b"OPS1"
48
+
49
+ #: Longest accepted ``key_type`` / ``key_id``, in UTF-8 bytes.
50
+ MAX_COMPONENT_BYTES = 4096
51
+
52
+ #: Provider ceiling on a record's value. Deliberately a generous superset of
53
+ #: core's ``MAX_PROTOCOL_STATE_RECORD_BYTES`` (4 MiB) plus its seal envelope, so
54
+ #: this never rejects a record the SDK legitimately wrote — it exists to bound
55
+ #: allocation for a file the SDK never wrote.
56
+ MAX_VALUE_BYTES = 8 * 1024 * 1024
57
+
58
+ #: Largest file the reader will pull into memory.
59
+ MAX_FILE_BYTES = 8 + 2 * MAX_COMPONENT_BYTES + MAX_VALUE_BYTES
60
+
61
+ #: Longest possible header, bounding the partial read ``list_keys`` does.
62
+ MAX_HEADER_BYTES = 8 + 2 * MAX_COMPONENT_BYTES
63
+
64
+ #: Ceiling on entries one ``list_keys`` will open. Core caps every category far
65
+ #: below this; a directory holding more has been tampered with.
66
+ #:
67
+ #: The bound counts entries *examined*, not keys returned. Counting the latter
68
+ #: would not bound the tampered case at all — the case this exists for: an entry
69
+ #: whose header does not parse yields no key, so a directory full of unparseable
70
+ #: ``k_`` files would be opened in its entirety on every launch while the counter
71
+ #: sat at zero.
72
+ MAX_LISTED_KEYS = 65_536
73
+
74
+ #: Prefix of the temporary file ``store`` writes before renaming it into place.
75
+ #: Distinct from the ``k_`` entry prefix so enumeration never mistakes a
76
+ #: half-written record for one.
77
+ TEMP_PREFIX = ".write-"
78
+
79
+ #: Ceiling on entries one stale-temporary sweep examines, so a tampered
80
+ #: directory cannot turn the first store of a session into an unbounded scan.
81
+ MAX_SWEEP_ENTRIES = 4_096
82
+
83
+ #: Serialises every store, load, delete, and enumeration in the process.
84
+ #:
85
+ #: Deliberately module-level, matching the Android provider's companion-object
86
+ #: lock rather than the per-instance lock this used to be. Two providers over
87
+ #: one root are not hypothetical, and a per-instance lock cannot order them by
88
+ #: construction. That matters most for :meth:`AppStateStorage._sweep_temporaries`,
89
+ #: whose whole safety argument is that no temporary another writer is using can
90
+ #: be visible while the lock is held: with an instance lock, one provider's
91
+ #: sweep can unlink the ``mkstemp`` file another provider's ``os.replace`` is
92
+ #: about to rename into place, turning a store that would have succeeded into a
93
+ #: ``StoreFailed``.
94
+ #:
95
+ #: Contention across accounts is not a concern: these are short file operations,
96
+ #: and the SDK already serialises storage access behind its own mutex.
97
+ _STORE_LOCK = threading.RLock()
98
+
99
+
100
+ def _digest(*components: str) -> str:
101
+ sha = hashlib.sha256()
102
+ for component in components:
103
+ sha.update(component.encode("utf-8"))
104
+ sha.update(b"\x00")
105
+ return sha.hexdigest()
106
+
107
+
108
+ def _type_directory_name(key_type: str) -> str:
109
+ return f"t_{_digest(key_type)}"
110
+
111
+
112
+ def _entry_name(key_type: str, key_id: str) -> str:
113
+ return f"k_{_digest(key_type, key_id)}"
114
+
115
+
116
+ def _frame(key_type: str, key_id: str, value: bytes) -> bytes:
117
+ type_bytes = key_type.encode("utf-8")
118
+ id_bytes = key_id.encode("utf-8")
119
+ if len(type_bytes) > MAX_COMPONENT_BYTES or len(id_bytes) > MAX_COMPONENT_BYTES:
120
+ raise MlsStorageError.StoreFailed(
121
+ f"protocol-state key exceeds {MAX_COMPONENT_BYTES} bytes"
122
+ )
123
+ if len(value) > MAX_VALUE_BYTES:
124
+ raise MlsStorageError.StoreFailed(
125
+ f"protocol-state record is {len(value)} bytes, over the "
126
+ f"{MAX_VALUE_BYTES} byte limit"
127
+ )
128
+ return b"".join(
129
+ (
130
+ RECORD_MAGIC,
131
+ len(type_bytes).to_bytes(2, "big"),
132
+ len(id_bytes).to_bytes(2, "big"),
133
+ type_bytes,
134
+ id_bytes,
135
+ value,
136
+ )
137
+ )
138
+
139
+
140
+ def _parse_header(raw: bytes) -> tuple[str, str, int] | None:
141
+ """Return ``(key_type, key_id, value_offset)``, or ``None`` when *raw* is
142
+ not a record this SDK wrote."""
143
+ if len(raw) < 8 or raw[:4] != RECORD_MAGIC:
144
+ return None
145
+ type_len = int.from_bytes(raw[4:6], "big")
146
+ id_len = int.from_bytes(raw[6:8], "big")
147
+ if type_len > MAX_COMPONENT_BYTES or id_len > MAX_COMPONENT_BYTES:
148
+ return None
149
+ if len(raw) < 8 + type_len + id_len:
150
+ return None
151
+ try:
152
+ key_type = raw[8 : 8 + type_len].decode("utf-8")
153
+ key_id = raw[8 + type_len : 8 + type_len + id_len].decode("utf-8")
154
+ except UnicodeDecodeError:
155
+ return None
156
+ return key_type, key_id, 8 + type_len + id_len
157
+
158
+
159
+ def _default_root() -> Path:
160
+ configured = os.environ.get(_STATE_ROOT_ENV)
161
+ if configured:
162
+ return Path(configured)
163
+ raise ValueError(
164
+ "protocol state has no safe process-wide default; pass root=... or set "
165
+ f"{_STATE_ROOT_ENV} to an application-owned directory that is removed "
166
+ "when the application is uninstalled"
167
+ )
168
+
169
+
170
+ #: Mode for every directory this provider creates: owner-only.
171
+ #:
172
+ #: iOS and Android get container isolation from the OS. Python's container is
173
+ #: whatever directory the application names, which on a shared host is created
174
+ #: at the process umask — typically world-listable. Record *files* are already
175
+ #: owner-only (``mkstemp`` creates them 0600 and ``os.replace`` preserves that),
176
+ #: so contents are safe either way; what a listable directory leaks is the entry
177
+ #: count and, because the filename digest is unsalted, a confirmation oracle for
178
+ #: any guessable peer or message id. That is the peer graph the confidentiality
179
+ #: notes tell applications to treat as exposed only to someone who can already
180
+ #: read the container.
181
+ _DIRECTORY_MODE = 0o700
182
+
183
+
184
+ def _private_mkdir(directory: Path) -> None:
185
+ """Create *directory* owner-only, tightening it if it already exists.
186
+
187
+ ``mkdir(mode=...)`` is masked by the process umask and does nothing at all
188
+ when the directory is already there, so the explicit ``chmod`` is what makes
189
+ the mode deterministic — including for a store created by an earlier version
190
+ of this provider. Parents are left alone: they are application-chosen paths
191
+ that this provider does not own.
192
+
193
+ Best effort on the ``chmod``: filesystems without POSIX permissions (and
194
+ Windows) refuse it, and there the directory mode was never a control anyway.
195
+ """
196
+
197
+ directory.mkdir(mode=_DIRECTORY_MODE, parents=True, exist_ok=True)
198
+ try:
199
+ directory.chmod(_DIRECTORY_MODE)
200
+ except OSError:
201
+ pass
202
+
203
+
204
+ def _sync_directory(directory: Path) -> None:
205
+ """Flush a directory entry so a rename or unlink in it survives a crash.
206
+
207
+ ``fsync`` on the temporary file only makes its *contents* durable; the link
208
+ that ``os.replace`` (or ``unlink``) creates or removes lives in the parent
209
+ directory and needs its own flush. Without this a power loss can lose a
210
+ store the SDK was told succeeded — most sharply for the sealed record key's
211
+ counterpart records — or resurrect a deleted outbox entry and resend work
212
+ that was already settled.
213
+
214
+ Best effort: directories cannot be opened for ``fsync`` on every platform
215
+ (notably Windows), and there the file-level ``fsync`` above remains the
216
+ strongest guarantee available.
217
+ """
218
+ try:
219
+ descriptor = os.open(directory, os.O_RDONLY)
220
+ except OSError:
221
+ return
222
+ try:
223
+ os.fsync(descriptor)
224
+ except OSError:
225
+ pass
226
+ finally:
227
+ os.close(descriptor)
228
+
229
+
230
+ class AppStateStorage(ProtocolStateStorageProvider):
231
+ """Atomic application-data storage kept outside the OS credential store."""
232
+
233
+ def __init__(
234
+ self,
235
+ root: str | Path | None = None,
236
+ *,
237
+ namespace: str | None = None,
238
+ ) -> None:
239
+ base_root = Path(root) if root is not None else _default_root()
240
+ self._root = (
241
+ base_root / require_account_storage_namespace(namespace)
242
+ if namespace is not None
243
+ else base_root
244
+ )
245
+ #: Type directories whose stale temporaries have already been swept by
246
+ #: this provider. Kept per instance rather than module-level because the
247
+ #: sweep is idempotent, so a second provider repeating it once costs one
248
+ #: bounded scan and nothing else — while the *safety* of that scan comes
249
+ #: from ``_STORE_LOCK``, not from this set.
250
+ self._swept: set[Path] = set()
251
+ try:
252
+ _private_mkdir(self._root)
253
+ except OSError as exc:
254
+ raise MlsStorageError.StoreFailed(
255
+ f"failed to create protocol-state directory: {exc}"
256
+ ) from exc
257
+
258
+ def store(self, key_type: str, key_id: str, data: bytes) -> None:
259
+ framed = _frame(key_type, key_id, data)
260
+ with _STORE_LOCK:
261
+ directory = self._type_directory(key_type)
262
+ try:
263
+ _private_mkdir(directory)
264
+ self._sweep_temporaries(directory)
265
+ descriptor, temporary = tempfile.mkstemp(prefix=TEMP_PREFIX, dir=directory)
266
+ try:
267
+ with os.fdopen(descriptor, "wb") as handle:
268
+ handle.write(framed)
269
+ handle.flush()
270
+ os.fsync(handle.fileno())
271
+ os.replace(temporary, self._entry_path(key_type, key_id))
272
+ _sync_directory(directory)
273
+ except BaseException:
274
+ try:
275
+ os.unlink(temporary)
276
+ except FileNotFoundError:
277
+ pass
278
+ raise
279
+ except OSError as exc:
280
+ raise MlsStorageError.StoreFailed(
281
+ f"failed to persist protocol state: {exc}"
282
+ ) from exc
283
+
284
+ def load(self, key_type: str, key_id: str) -> bytes | None:
285
+ with _STORE_LOCK:
286
+ path = self._entry_path(key_type, key_id)
287
+ try:
288
+ # Stat before reading. A record over the ceiling cannot have
289
+ # been written through ``store``, so it is corrupt or tampered —
290
+ # removing it keeps a poison file from being re-examined on
291
+ # every boot, and keeps the read itself from becoming an
292
+ # unbounded allocation.
293
+ with open(path, "rb") as handle:
294
+ oversized = os.fstat(handle.fileno()).st_size > MAX_FILE_BYTES
295
+ # Read one byte past the ceiling so a stat that raced a
296
+ # concurrent writer (or a filesystem that misreports size)
297
+ # is still caught below.
298
+ raw = b"" if oversized else handle.read(MAX_FILE_BYTES + 1)
299
+ except FileNotFoundError:
300
+ return None
301
+ except OSError as exc:
302
+ raise MlsStorageError.LoadFailed(
303
+ f"failed to load protocol state: {exc}"
304
+ ) from exc
305
+
306
+ # Unlink outside the `with`: Windows refuses to remove an open file.
307
+ if oversized or len(raw) > MAX_FILE_BYTES:
308
+ raise self._discard(path, "record is over the ceiling")
309
+
310
+ header = _parse_header(raw)
311
+ if header is None or header[0] != key_type or header[1] != key_id:
312
+ # Malformed framing, or a name that resolves to some other
313
+ # record: either way this is not the entry that was asked for.
314
+ raise self._discard(
315
+ path, f"record framing does not name {key_type}/{key_id}"
316
+ )
317
+ return raw[header[2] :]
318
+
319
+ def delete(self, key_type: str, key_id: str) -> None:
320
+ with _STORE_LOCK:
321
+ path = self._entry_path(key_type, key_id)
322
+ try:
323
+ path.unlink()
324
+ except FileNotFoundError:
325
+ return
326
+ except OSError as exc:
327
+ raise MlsStorageError.DeleteFailed(
328
+ f"failed to delete protocol state: {exc}"
329
+ ) from exc
330
+ _sync_directory(path.parent)
331
+
332
+ def list_keys(self, key_type: str) -> list[str]:
333
+ return self.enumerate_keys(key_type, MAX_LISTED_KEYS)[0]
334
+
335
+ def enumerate_keys(self, key_type: str, limit: int) -> tuple[list[str], int]:
336
+ """Enumerate one category, opening at most ``limit`` entries.
337
+
338
+ ``limit`` bounds the entries *examined* rather than the keys collected,
339
+ because opening a file is the cost and an entry that fails to parse
340
+ yields no key: a directory of unparseable records must not be walked in
341
+ full on every launch. Exposed with an explicit ``limit`` so the bound is
342
+ testable without materializing tens of thousands of files.
343
+
344
+ Key ids are deduped: a name that resolves to a record already seen (a
345
+ copy planted in the container) must not make the same id appear twice.
346
+
347
+ Returns the sorted key ids and the number of entries examined.
348
+ """
349
+ with _STORE_LOCK:
350
+ directory = self._type_directory(key_type)
351
+ if not directory.exists():
352
+ return [], 0
353
+ keys: set[str] = set()
354
+ examined = 0
355
+ try:
356
+ # Stream the directory rather than materializing it, and read
357
+ # only each record's header: enumeration must stay bounded even
358
+ # when the container has been tampered with.
359
+ with os.scandir(directory) as entries:
360
+ for entry in entries:
361
+ if examined >= limit:
362
+ break
363
+ if not entry.name.startswith("k_"):
364
+ continue
365
+ examined += 1
366
+ if not entry.is_file():
367
+ continue
368
+ header = self._read_header(Path(entry.path))
369
+ if header is not None and header[0] == key_type:
370
+ keys.add(header[1])
371
+ except OSError as exc:
372
+ raise MlsStorageError.LoadFailed(
373
+ f"failed to list protocol-state keys: {exc}"
374
+ ) from exc
375
+ return sorted(keys), examined
376
+
377
+ # -- internals -----------------------------------------------------------
378
+
379
+ def _sweep_temporaries(self, directory: Path) -> None:
380
+ """Remove temporaries a previous process died before renaming.
381
+
382
+ ``store`` writes to a ``mkstemp`` file and renames it into place, so a
383
+ crash in between orphans that file permanently — and enumeration
384
+ filters on the ``k_`` prefix, so nothing ever sees it again. Left alone
385
+ they accumulate for the life of the install, in a directory the
386
+ application cannot reasonably be asked to clean itself.
387
+
388
+ Safe to unlink unconditionally *because the lock is process-wide*:
389
+ ``store`` holds ``_STORE_LOCK`` for the whole write, so no temporary any
390
+ writer in this process is using can be visible here. That is the entire
391
+ safety argument, and it is why the lock is module-level rather than per
392
+ instance — an instance lock cannot order two providers over one root.
393
+ Runs once per type directory per instance — the caller is the first
394
+ store into that category, which keeps it off the restore path — and is
395
+ best effort, since losing the race with another process's rename costs
396
+ nothing.
397
+ """
398
+
399
+ if directory in self._swept:
400
+ return
401
+ self._swept.add(directory)
402
+ try:
403
+ with os.scandir(directory) as entries:
404
+ for examined, entry in enumerate(entries):
405
+ if examined >= MAX_SWEEP_ENTRIES:
406
+ break
407
+ if not entry.name.startswith(TEMP_PREFIX):
408
+ continue
409
+ try:
410
+ os.unlink(entry.path)
411
+ except OSError:
412
+ continue
413
+ logger.debug("removed stale protocol-state temporary %s", entry.name)
414
+ except OSError:
415
+ # A directory we cannot scan is not a reason to fail the store that
416
+ # is about to create it fresh.
417
+ return
418
+
419
+ @staticmethod
420
+ def _read_header(path: Path) -> tuple[str, str, int] | None:
421
+ try:
422
+ with open(path, "rb") as handle:
423
+ return _parse_header(handle.read(MAX_HEADER_BYTES))
424
+ except OSError:
425
+ return None
426
+
427
+ @staticmethod
428
+ def _discard(path: Path, reason: str) -> Exception:
429
+ """Remove a record that can never be read and return the error saying so.
430
+
431
+ ``CorruptedData``, not a silent ``None``: absence and destruction are
432
+ different answers upstream. The SDK settles a destroyed record — the
433
+ application is holding the message id ``send_message`` returned for it —
434
+ while absence is simply nothing to restore, reported to no one.
435
+ """
436
+
437
+ logger.warning("dropping protocol-state record %s: %s", path.name, reason)
438
+ try:
439
+ path.unlink()
440
+ except OSError:
441
+ pass
442
+ else:
443
+ _sync_directory(path.parent)
444
+ return MlsStorageError.CorruptedData(
445
+ f"dropped unreadable protocol-state record: {reason}"
446
+ )
447
+
448
+ def _type_directory(self, key_type: str) -> Path:
449
+ return self._root / _type_directory_name(key_type)
450
+
451
+ def _entry_path(self, key_type: str, key_id: str) -> Path:
452
+ return self._type_directory(key_type) / _entry_name(key_type, key_id)
@@ -0,0 +1,33 @@
1
+ """Stable account namespaces for built-in protocol storage."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import hashlib
6
+ import re
7
+
8
+ _NAMESPACE_DOMAIN = b"offline-protocol-storage-v1"
9
+
10
+ _ACCOUNT_PATTERN = re.compile(r"\Aaccount-[0-9a-f]{64}\Z")
11
+
12
+
13
+ def account_storage_namespace(app_id: str, profile: str) -> str:
14
+ """Return an opaque, filesystem-safe namespace for one protocol account."""
15
+
16
+ digest = hashlib.sha256(
17
+ _NAMESPACE_DOMAIN + b"\0" + app_id.encode("utf-8") + b"\0" + profile.encode("utf-8")
18
+ ).hexdigest()
19
+ return f"account-{digest}"
20
+
21
+
22
+ def require_account_storage_namespace(value: str) -> str:
23
+ """Return *value* if it is a well-formed account namespace, else raise.
24
+
25
+ Built-in stores turn a namespace into a path or credential-store component,
26
+ so an arbitrary caller-supplied string could escape its own account (``..``)
27
+ or collide with another's. Mirrors ``StorageNamespace.requireAccount`` on
28
+ Android and iOS.
29
+ """
30
+
31
+ if not _ACCOUNT_PATTERN.match(value):
32
+ raise ValueError("Invalid protocol storage account namespace")
33
+ return value