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,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
|