erdigo-sdk 1.0.0__tar.gz

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 (30) hide show
  1. erdigo_sdk-1.0.0/LICENSE +21 -0
  2. erdigo_sdk-1.0.0/MANIFEST.in +2 -0
  3. erdigo_sdk-1.0.0/PKG-INFO +432 -0
  4. erdigo_sdk-1.0.0/README.md +405 -0
  5. erdigo_sdk-1.0.0/pyproject.toml +48 -0
  6. erdigo_sdk-1.0.0/setup.cfg +4 -0
  7. erdigo_sdk-1.0.0/src/erdigo_sdk/__init__.py +50 -0
  8. erdigo_sdk-1.0.0/src/erdigo_sdk/__main__.py +7 -0
  9. erdigo_sdk-1.0.0/src/erdigo_sdk/_windows.py +254 -0
  10. erdigo_sdk-1.0.0/src/erdigo_sdk/cli.py +585 -0
  11. erdigo_sdk-1.0.0/src/erdigo_sdk/client.py +608 -0
  12. erdigo_sdk-1.0.0/src/erdigo_sdk/discovery.py +155 -0
  13. erdigo_sdk-1.0.0/src/erdigo_sdk/errors.py +118 -0
  14. erdigo_sdk-1.0.0/src/erdigo_sdk/identity.py +78 -0
  15. erdigo_sdk-1.0.0/src/erdigo_sdk/messages.py +700 -0
  16. erdigo_sdk-1.0.0/src/erdigo_sdk/model.py +399 -0
  17. erdigo_sdk-1.0.0/src/erdigo_sdk/noise.py +420 -0
  18. erdigo_sdk-1.0.0/src/erdigo_sdk/pairing.py +203 -0
  19. erdigo_sdk-1.0.0/src/erdigo_sdk/private_file.py +223 -0
  20. erdigo_sdk-1.0.0/src/erdigo_sdk/protocol.py +120 -0
  21. erdigo_sdk-1.0.0/src/erdigo_sdk/store.py +364 -0
  22. erdigo_sdk-1.0.0/src/erdigo_sdk/stream.py +201 -0
  23. erdigo_sdk-1.0.0/src/erdigo_sdk/strict_json.py +439 -0
  24. erdigo_sdk-1.0.0/src/erdigo_sdk/terminal.py +135 -0
  25. erdigo_sdk-1.0.0/src/erdigo_sdk.egg-info/PKG-INFO +432 -0
  26. erdigo_sdk-1.0.0/src/erdigo_sdk.egg-info/SOURCES.txt +28 -0
  27. erdigo_sdk-1.0.0/src/erdigo_sdk.egg-info/dependency_links.txt +1 -0
  28. erdigo_sdk-1.0.0/src/erdigo_sdk.egg-info/entry_points.txt +2 -0
  29. erdigo_sdk-1.0.0/src/erdigo_sdk.egg-info/requires.txt +9 -0
  30. erdigo_sdk-1.0.0/src/erdigo_sdk.egg-info/top_level.txt +1 -0
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Ziorentia
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,2 @@
1
+ # The tests need the rest of the repository (spec/vectors, the mock receivers), so they run from a clone.
2
+ prune tests
@@ -0,0 +1,432 @@
1
+ Metadata-Version: 2.4
2
+ Name: erdigo-sdk
3
+ Version: 1.0.0
4
+ Summary: Write pins, markers, notes, photos and tracks to an Erdigo receiver on the local network.
5
+ Author: Ziorentia LLC
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://www.ziorentia.com/product.php?id=erdigo
8
+ Project-URL: Documentation, https://github.com/Ziorentia/Erdigo-sdk/blob/main/python/README.md
9
+ Project-URL: Source, https://github.com/Ziorentia/Erdigo-sdk
10
+ Project-URL: Issues, https://github.com/Ziorentia/Erdigo-sdk/issues
11
+ Project-URL: Changelog, https://github.com/Ziorentia/Erdigo-sdk/releases
12
+ Keywords: erdigo,map,gps,location,iot,sensors,local network,noise protocol
13
+ Classifier: Programming Language :: Python :: 3
14
+ Classifier: Operating System :: POSIX :: Linux
15
+ Classifier: Operating System :: MacOS
16
+ Classifier: Operating System :: Microsoft :: Windows
17
+ Classifier: Intended Audience :: Developers
18
+ Classifier: Topic :: Scientific/Engineering :: GIS
19
+ Requires-Python: >=3.10
20
+ Description-Content-Type: text/markdown
21
+ License-File: LICENSE
22
+ Requires-Dist: cryptography>=50.0.2
23
+ Provides-Extra: discovery
24
+ Requires-Dist: zeroconf>=0.154.0; python_version >= "3.11" and extra == "discovery"
25
+ Requires-Dist: zeroconf>=0.152.0; python_version < "3.11" and extra == "discovery"
26
+ Dynamic: license-file
27
+
28
+ # Erdigo SDK for Python
29
+
30
+ A Python library and command-line tool for writing pins, markers, notes, photos and tracks to an Erdigo receiver on
31
+ the local network. It needs Python 3.10 or later and runs on Linux, macOS and Windows.
32
+
33
+ This is the edition for scripts and for Linux boards such as a Raspberry Pi: a sensor gateway, a ground station or a
34
+ cron job that reads its readings in its own way and sends them through the SDK. **It has not been tried on a real
35
+ Raspberry Pi or any other ARM board.** Its tests run on Linux (x64) and Windows (x64) in CI, and on macOS (Apple
36
+ silicon) locally.
37
+
38
+ It speaks the same [protocol](https://github.com/Ziorentia/Erdigo-sdk/blob/main/spec/integration-v1.md) as the [Swift](https://github.com/Ziorentia/Erdigo-sdk/blob/main/swift/README.md) and
39
+ [.NET](https://github.com/Ziorentia/Erdigo-sdk/blob/main/dotnet/README.md) SDKs, and its `erdigo-send` tool has the same commands and options as theirs. It has no
40
+ mock receiver of its own: develop against the mock that comes with either of them. CI pairs with the .NET mock and
41
+ writes every item kind to it, and the same was done with the Swift mock on a Mac.
42
+
43
+ To use the SDK with a real map, install Erdigo 2.17.23 or later on a Mac from the
44
+ [Mac App Store](https://apps.apple.com/us/app/erdigo/id6446225102?mt=12) or on a PC from the
45
+ [Microsoft Store](https://apps.microsoft.com/detail/9ndwqg2sdr7x?hl=en-US), on the same local network. The app's
46
+ minimum and recommended systems are listed in [System requirements for the app](https://github.com/Ziorentia/Erdigo-sdk/blob/main/README.md#system-requirements-for-the-app).
47
+
48
+ ## Install
49
+
50
+ Install it from [PyPI](https://pypi.org/project/erdigo-sdk/) into a virtual environment:
51
+
52
+ ```bash
53
+ python3 -m venv .venv
54
+ .venv/bin/pip install erdigo-sdk
55
+ ```
56
+
57
+ On Windows the second line is `.venv\Scripts\pip install erdigo-sdk`. To find receivers on the network without giving
58
+ an address, add the optional discovery package: `pip install "erdigo-sdk[discovery]"`. Everything else works without
59
+ it. To change the SDK itself, install it from a full clone of this repository instead: `pip install ./python`.
60
+
61
+ That installs `erdigo-send`, which `python -m erdigo_sdk` also runs. The one dependency is `cryptography`, which has
62
+ ready-made wheels for 64-bit Linux on x64 and ARM, macOS and Windows. On a 32-bit Raspberry Pi OS pip may have to build
63
+ it, which needs Rust; use the 64-bit system where you can. Neither has been tried.
64
+
65
+ ## Try it in two minutes
66
+
67
+ These steps use a clone of this repository: `git clone https://github.com/Ziorentia/Erdigo-sdk.git`.
68
+
69
+ Start a mock receiver from one of the other SDKs in one terminal. With the [.NET 8 SDK](https://dotnet.microsoft.com/download/dotnet/8.0),
70
+ in the `dotnet` folder:
71
+
72
+ ```bash
73
+ dotnet run --project src/erdigo-send -- serve --mock
74
+ ```
75
+
76
+ or with Xcode or the Swift command-line tools, at the top of the repository: `swift run erdigo-send serve --mock`.
77
+
78
+ It prints a port, a pairing code and the receiver's key. In another terminal, pair with it. Type the code when asked.
79
+ The tool then shows the key it found: if it matches the one the mock printed, type `yes`. The mock is not asked to pair,
80
+ and no pairing is saved, until you do.
81
+
82
+ ```bash
83
+ .venv/bin/erdigo-send pair --host 127.0.0.1 --port PORT --name "My sensor" --kinds pin,track --label test
84
+ ```
85
+
86
+ Then send something:
87
+
88
+ ```bash
89
+ .venv/bin/erdigo-send pin --host 127.0.0.1 --port PORT --id city-hall --lat 37.5663 --lon 126.9779 --title "Seoul City Hall"
90
+ ```
91
+
92
+ The mock prints each request it accepts. Type `devices` and then `items 1` in its terminal to see what it holds. The
93
+ other SDKs' guides describe the mock's options.
94
+
95
+ ## Use it in your code
96
+
97
+ Pair once:
98
+
99
+ ```python
100
+ import sys
101
+
102
+ from erdigo_sdk import DISCOVER, FileDeviceStore, ItemKind, PairingTicket, default_directory, pair
103
+
104
+ store = FileDeviceStore(default_directory())
105
+ identity = store.load_or_create_identity()
106
+
107
+ # Read this from the keyboard or from a private file. Never take it as a command-line argument.
108
+ ticket = PairingTicket.parse(code_the_user_typed)
109
+
110
+
111
+ def confirm_key(key: str) -> bool:
112
+ """Asked only for a typed code, which proves only that the other side knows the code."""
113
+ if not (sys.stdin.isatty() and sys.stdout.isatty()):
114
+ return False # Nobody could see this and answer.
115
+ print(f"Receiver key: {key}")
116
+ return input("If this matches the key shown on the receiver, type yes: ").strip().lower() == "yes"
117
+
118
+
119
+ pairing = pair(DISCOVER, ticket, identity, "Greenhouse sensor", [ItemKind.PIN, ItemKind.TRACK], confirm_key=confirm_key)
120
+ store.save(pairing)
121
+ ```
122
+
123
+ `confirm_key` runs before the receiver hears about this device, so the receiver still shows its key. If it returns
124
+ false, `pair` raises an `ErdigoError` whose `kind` is `ErrorKind.KEY_NOT_CONFIRMED`, which a real program should catch.
125
+ The receiver has heard nothing about this device, and the code stays valid. If it returns true and the pairing
126
+ connection then meets silence, `pair` tries it up to three times, half a second and then a second apart, because the
127
+ receiver may still be counting out the connection that showed the key; this is safe, as nothing about this device is
128
+ sent until the receiver has proven the code and its key matches the one the person confirmed. A typed code cannot pair
129
+ without `confirm_key`. Text from the QR code carries the receiver's key, and `pair` compares it and stops on a mismatch,
130
+ so it asks the person nothing. `PairingTicket.parse` refuses QR text without a valid fingerprint. The terminal check
131
+ makes a pipe or a file count as a no, because nobody is there to see the key and answer, so a program with no terminal
132
+ should use the QR text. The [threat model](https://github.com/Ziorentia/Erdigo-sdk/blob/main/spec/threat-model.md#what-this-does-not-protect-against) explains why this
133
+ matters.
134
+
135
+ After that, write:
136
+
137
+ ```python
138
+ from erdigo_sdk import Coordinate, ErdigoClient, MarkerColor, TrackPoint
139
+
140
+ with ErdigoClient(identity, pairing, store) as client:
141
+ spot = Coordinate(37.5663, 126.9779)
142
+ client.put_pin("sensor-1", spot, "Greenhouse")
143
+ client.put_marker("gate", spot, "Gate", MarkerColor.GREEN)
144
+ client.move("sensor-1", spot)
145
+
146
+ client.append_track("walk", [TrackPoint(spot, timestamp_ms=1_700_000_000_000, altitude_m=38.5)], "Morning walk")
147
+ client.finish_track("walk")
148
+
149
+ client.put_photo("view", spot, jpeg_or_png_bytes, "View")
150
+ client.put_note("reminder", spot, "Check the vent.")
151
+
152
+ client.delete("reminder")
153
+ client.delete_all() # Only this device's items.
154
+ ```
155
+
156
+ [`examples/quickstart.py`](https://github.com/Ziorentia/Erdigo-sdk/blob/main/python/examples/quickstart.py) is a complete program. The API is synchronous, and a client may be
157
+ shared between threads: requests run one at a time, in the order they were made.
158
+
159
+ ## What the SDK does for you
160
+
161
+ - **Finds the receiver.** It tries the last known address, then up to eight receivers advertised on the local
162
+ network, if the optional `zeroconf` package is installed. Pass `ReceiverTarget.address(host, port)` to skip this.
163
+ - **Keeps requests in order.** They run one at a time, in the order they were made, and each returns once the receiver
164
+ acknowledges it. A long `append_track` and a photo upload are not interleaved with other requests.
165
+ - **Survives a sleeping computer or a closed app.** If the connection fails, it reconnects with growing delays (1, 2,
166
+ 4 ... up to 60 seconds, with 20 percent jitter) and resends with the same sequence number, so nothing is applied
167
+ twice. Choose how long with `retry=` (`RetryPolicy.NONE`, `RetryPolicy.up_to(seconds)` or `RetryPolicy.FOREVER`).
168
+ The default is 30 seconds, counted from when the connection was lost. See
169
+ [How long a request can take](#how-long-a-request-can-take).
170
+ - **Paces itself** by the limits the receiver announces, and waits when told to slow down. Waiting as told is never
171
+ held against a device. An answer that ends the connection is recognised before any wait, so it is never resent.
172
+ - **Splits large uploads.** Photos go in chunks of 48000 bytes, and a long list of track points goes in batches of 100.
173
+
174
+ ## How long a request can take
175
+
176
+ The retry policy limits each outage, not the request as a whole. Its time counts from when the connection was lost
177
+ and starts again once a connection is made, and time spent connected, such as waiting to stay within the receiver's
178
+ limits, never counts. So a receiver that keeps accepting connections and losing them before it answers keeps a request
179
+ going past 30 seconds, and the requests behind it wait. When a request must end within a fixed time, give it one:
180
+
181
+ ```python
182
+ try:
183
+ client.put_pin("sensor-1", spot, "Greenhouse", timeout=120)
184
+ except TimeoutError:
185
+ ... # Not confirmed in time. See below.
186
+ ```
187
+
188
+ The time includes waiting for its turn. A request that runs out of time while waiting frees its place at once, and the
189
+ ones behind it go ahead. A request that runs out after it was sent may already have been applied, because the receiver
190
+ may have acted on it before the answer was lost. Sending it again is safe for the `put_…` methods, `move` and the
191
+ deletes, which give the same result when repeated. `append_track` would add its points a second time, and a long one
192
+ may have sent some of its batches already.
193
+
194
+ ## When something goes wrong
195
+
196
+ Requests raise `ErdigoError`, and its `kind` says what happened. The one you will meet most is `NO_ANSWER`. A receiver
197
+ stays silent when it is off, asleep or on another network, when a pairing code is wrong or expired, and when a device
198
+ has been removed. These cannot be told apart, on purpose, because that silence is what keeps strangers from learning
199
+ anything.
200
+
201
+ | `ErrorKind` | Meaning |
202
+ |---|---|
203
+ | `NO_ANSWER` | See above. Check the network and that the app is running. |
204
+ | `NOT_PERMITTED` | The person did not allow this kind (`item_kind`). Pair again to ask for more. |
205
+ | `REJECTED` | The receiver refused this request. `receiver_error.code` is listed in the [specification](https://github.com/Ziorentia/Erdigo-sdk/blob/main/spec/integration-v1.md#10-errors). |
206
+ | `KEY_NOT_CONFIRMED` | With a typed code, `confirm_key` returned false. The receiver was not asked to pair, and the code still works. |
207
+ | `FINGERPRINT_MISMATCH` | The receiver's key is not the one in the QR text or `--fingerprint`. Nothing was sent about this device. |
208
+ | `PAIRING_DENIED`, `PAIRING_TIMED_OUT` | The person declined, or did not answer in time. |
209
+ | `CODE_REUSED` | The code was already used. Ask for a new one. |
210
+ | `VERSION_UNSUPPORTED` | Update the SDK. |
211
+ | `REPLACED`, `SEQUENCE_CONFLICT` | Two programs are using one device key. Give each its own key, or its own `--profile` with `erdigo-send`. |
212
+ | `STORAGE` | Stored state could not be used. `storage_problem` says why. A device key that exists but cannot be read is never replaced. |
213
+ | `INVALID_ARGUMENT` | Refused before anything was sent, such as an empty title or a GIF. |
214
+
215
+ ## Where things are kept
216
+
217
+ `FileDeviceStore` keeps one identity and its pairings in a folder of its own. `default_directory(profile)` is:
218
+
219
+ | System | Folder |
220
+ |---|---|
221
+ | Linux | `$XDG_DATA_HOME/ErdigoSDK.Python/<profile>/`, by default `~/.local/share/ErdigoSDK.Python/<profile>/` |
222
+ | macOS | `~/Library/Application Support/ErdigoSDK.Python/<profile>/` |
223
+ | Windows | `%LOCALAPPDATA%\ErdigoSDK.Python\<profile>\` |
224
+
225
+ The folder's name differs from the other SDKs' on purpose, so that they never share a device key. Pairings and
226
+ connection counters are in `pairings.json`. Every file is written through a temporary file and a rename, so a crash
227
+ never leaves half a file, and a lock file keeps two processes from writing at once.
228
+
229
+ **On Linux and macOS** the folder has mode 0700 and its files mode 0600, and the store refuses a folder or file that
230
+ is a link, belongs to another user or can be read by anyone else. The device key is in `identity.key` in the clear,
231
+ protected only by those permissions. Someone with your user account or root can read it, and so can anyone with a copy
232
+ of a backup that holds it. On a Raspberry Pi that runs a sensor, give the program a user account of its own.
233
+
234
+ **On Windows** the store creates the folder with a protected access list that grants the current user alone, and
235
+ refuses a folder or file that grants anyone but the current user, SYSTEM and the Administrators group. The device key is
236
+ in `identity.dpapi`, encrypted with [DPAPI](https://learn.microsoft.com/windows/win32/api/dpapi/nf-dpapi-cryptprotectdata)
237
+ for the current user, with entropy that ties it to this purpose, called through `ctypes`. DPAPI keeps the key from other
238
+ users and from someone who copies the file to another computer. It does not protect against a program running as you,
239
+ an administrator, or someone with your password and a copy of your profile. The
240
+ [.NET SDK guide](https://github.com/Ziorentia/Erdigo-sdk/blob/main/dotnet/README.md#what-dpapi-does-not-protect-against) says more.
241
+
242
+ The store tells these apart, and never makes a new key over an old one:
243
+
244
+ | Key file | What happens |
245
+ |---|---|
246
+ | Missing | A new key is made and saved. |
247
+ | Damaged (not a key) | `StorageProblem.IDENTITY_DAMAGED`. The file is left as it is. |
248
+ | Unreadable (no permission, or DPAPI cannot decrypt it) | `StorageProblem.IDENTITY_UNREADABLE`. The file is left as it is. |
249
+ | Readable by others, or a link | `StorageProblem.INSECURE`. Nothing is read. |
250
+
251
+ To start again with a new identity, move the key file away yourself. A new key means pairing again with every receiver.
252
+
253
+ **Secrets in memory.** Python gives no way to wipe a key from memory: `bytes` cannot be cleared, and the interpreter and
254
+ the `cryptography` package make copies. The key stays in the process's memory while it runs, and a crash dump or swap
255
+ may hold a copy.
256
+
257
+ ## Dependencies, and why
258
+
259
+ | Package | Version tested | Why |
260
+ |---|---|---|
261
+ | `cryptography` | 50.0.2 | X25519 and ChaCha20-Poly1305, from OpenSSL. SHA-256, HMAC and HKDF come from Python itself. The Noise handshakes are implemented in this package and checked against the official vectors. |
262
+ | `zeroconf` | 0.154.0 (0.152.0 on Python 3.10) | Optional, for finding receivers on the network. |
263
+ | `pytest`, `setuptools` | 9.2.0, 84.2.1 | Tests and building only. |
264
+
265
+ [`pyproject.toml`](https://github.com/Ziorentia/Erdigo-sdk/blob/main/python/pyproject.toml) asks for these versions or later, so that the package installs beside
266
+ others that need `cryptography`. CI installs exactly what [`requirements/test.txt`](https://github.com/Ziorentia/Erdigo-sdk/blob/main/python/requirements/test.txt) lists, with a hash for every file, including
267
+ the packages these bring with them. Regenerate it after changing a version, with the command at the top of
268
+ [`requirements/test.in`](https://github.com/Ziorentia/Erdigo-sdk/blob/main/python/requirements/test.in). Nothing checks these packages against a list of known vulnerabilities
269
+ yet; check `cryptography`'s security advisories before updating it, and update it when one affects you.
270
+
271
+ ## Differences from the Swift and .NET SDKs
272
+
273
+ - **No mock receiver.** `erdigo-send serve --mock` says to use the .NET or Swift one, which this edition works with.
274
+ - **Synchronous.** Methods block until the receiver answers, and take `timeout=` in seconds where the others take a
275
+ cancellation token or a Swift task. A client can be shared between threads.
276
+ - **Discovery is optional** and uses the `zeroconf` package, which shares port 5353 with the system's own responder.
277
+ Without it, give an address. It has been checked only against the .NET mock's advertisement, on CI's Linux runner.
278
+ - **The key** is in a 0600 file on Linux and macOS, and encrypted with DPAPI on Windows. There is no keychain option,
279
+ so `erdigo-send --keychain` is refused.
280
+ - `erdigo-send pair` reads a typed code from the terminal itself on Linux and macOS, with echo off, as the other tools
281
+ do, and from the console on Windows. Either way a code file can be used.
282
+ - On Windows an access-list entry for OWNER RIGHTS is accepted when a trusted account owns the file or folder (see
283
+ [The `erdigo-send` tool](#the-erdigo-send-tool)). The .NET SDK refuses such an entry.
284
+
285
+ ## The `erdigo-send` tool
286
+
287
+ Run `erdigo-send help` for every command. Add `--redact` to a command when pasting its output into a bug report. To pair
288
+ with `--redact`, use the QR text or `--fingerprint`, because a hidden key cannot be compared.
289
+
290
+ `pair` asks you to compare the receiver's key and type `yes` when it has only a bare code. It asks before the receiver
291
+ hears any request, so the receiver still shows its key. Anything typed before the key appears is discarded. At the end
292
+ of input or on any other answer it exits with an error. No pairing is saved and the receiver is not asked to pair,
293
+ although this device's own key may be in the state folder by then. The receiver never sees that key. With the QR text
294
+ or `--fingerprint` it compares the key itself and asks nothing.
295
+
296
+ Only a person can answer that question, so `pair` refuses a bare code when standard input or output is not a terminal,
297
+ as in a pipe, a script or a systemd service. It stops before it contacts the receiver. Use the QR text there, or
298
+ `--fingerprint` with the full 64-digit key, which is part of the QR text.
299
+
300
+ `note --text-file` reads the note from a UTF-8 file. A note may hold line feeds and tabs but no carriage returns (spec
301
+ section 6.3), so the tool takes out what editors such as Notepad add: a byte order mark at the start, and the carriage
302
+ return of each Windows line ending (CR LF becomes LF). Nothing else is changed. A carriage return on its own is refused
303
+ before anything is sent, and the 4096-byte limit counts the note as it is sent. The other editions' tools do the same.
304
+
305
+ The code is never accepted as a command-line argument, because arguments appear in process lists and shell history. A
306
+ code file must be readable by you alone: on Linux and macOS a regular file you own with mode 0600, on Windows a file
307
+ that grants nobody but you, SYSTEM and the Administrators group. On Windows an entry for OWNER RIGHTS counts as the
308
+ file's owner, so it is accepted when you, SYSTEM or the Administrators group own the file. Python 3.13 and later give
309
+ folders made with mode 0o700, such as those from `tempfile.mkdtemp`, exactly that entry.
310
+
311
+ ## Cloud relay example
312
+
313
+ The app takes connections only from its own local network. For data that starts on the internet,
314
+ [`examples/cloud_relay`](https://github.com/Ziorentia/Erdigo-sdk/tree/main/python/examples/cloud_relay) has the two programs of the [cloud relay guide](https://github.com/Ziorentia/Erdigo-sdk/blob/main/docs/cloud-relay.md):
315
+
316
+ - `relay.py` runs on a server and holds what your devices send it over HTTPS until the gateway fetches it. It uses
317
+ only the Python standard library, so the one file can be copied to a server and run with Python 3.10 or later. It
318
+ speaks plain HTTP behind an HTTPS reverse proxy, and keeps its queue in memory.
319
+ - `gateway.py` runs on the app's local network. It fetches from the relay over outgoing HTTPS and writes to the app
320
+ through this SDK, as a paired device. It needs the SDK installed as above.
321
+
322
+ Neither is part of the installed package. From the root of the clone, with the virtual environment of
323
+ [Install](#install) and the tokens and addresses as placeholders:
324
+
325
+ ```bash
326
+ # On the server, which needs only Python and this one file
327
+ ERDIGO_RELAY_SOURCE_TOKENS=SOURCE_TOKEN ERDIGO_RELAY_GATEWAY_TOKEN=GATEWAY_TOKEN \
328
+ python3 python/examples/cloud_relay/relay.py --listen 127.0.0.1:8080
329
+
330
+ # On a computer on the app's network: pair once, then run
331
+ .venv/bin/python python/examples/cloud_relay/gateway.py pair --name "Cloud gateway" --host APP_HOST --port APP_PORT
332
+ ERDIGO_RELAY_TOKEN=GATEWAY_TOKEN .venv/bin/python python/examples/cloud_relay/gateway.py run --relay https://relay.example.com
333
+ ```
334
+
335
+ On Windows the gateway runs as `.venv\Scripts\python python\examples\cloud_relay\gateway.py`, with
336
+ `ERDIGO_RELAY_TOKEN` set in the environment first.
337
+
338
+ `pair` reads the code or the QR text from the keyboard, or from `--code-file`, as `erdigo-send pair` does. Without
339
+ `--host` and `--port` both commands look for the app on the network, which needs the optional discovery package. The
340
+ gateway keeps its key, its pairing and its place in the relay's queue (`relay-state.json`) in the profile
341
+ `cloud-gateway`, or in `--state-dir`; `erdigo-send list --profile cloud-gateway` shows its pairing. `run --once` does
342
+ not hold its fetches open, and stops as soon as the relay has nothing more. The relay API, every option, the exit codes
343
+ and how to deploy both are in the [guide](https://github.com/Ziorentia/Erdigo-sdk/blob/main/docs/cloud-relay.md).
344
+
345
+ While the app is out of reach or paused, the SDK keeps the operation and sends the same request again by itself, after
346
+ 1, 2, 4 ... up to 60 seconds, with the same sequence number, so the app applies it once even if its answer was lost
347
+ (spec sections 7 and 13). Without `--once` the gateway gives the SDK `RetryPolicy.FOREVER`, so this goes on for as long
348
+ as the app stays away; the gateway prints `No answer from the Erdigo app; trying again.` once per operation, without a
349
+ time, since only the SDK knows when it tries next. Ctrl+C, or `SIGTERM` on Linux and macOS, stops the gateway during
350
+ that wait too, with exit code 0, and the operation stays on the relay.
351
+
352
+ With `--once` the SDK gets `RetryPolicy.up_to(30)`, which gives up on an app it cannot connect to. That count starts
353
+ again at every new connection, so an app that takes every connection but never answers, or whose answers are all lost,
354
+ would keep it trying. The gateway therefore keeps its own count for each operation, from the first sign of trouble with
355
+ it: a connection the SDK made for it and then lost, or an answer that says "not now". It connects first and then sends,
356
+ and a watcher thread looks at `client.limits` while the request runs. Once the operation has been in trouble for 30
357
+ seconds the gateway gives up on it. The SDK cannot be stopped from another thread, so the store the gateway gives the
358
+ client refuses the next connect counter, and the request ends at its next connection without sending anything again.
359
+ An app that never answers shows trouble only when the SDK stops waiting for the answer, after 15 seconds, so that case
360
+ takes about 45 to 50 seconds. A request still going over a working connection is never cut short, so the time the SDK
361
+ spends pacing a track's points, up to about 100 seconds for 100 points, cannot make the gateway give up on a slow but
362
+ healthy operation.
363
+
364
+ The gateway then exits with code 3, as it does when the relay could not be reached or answered `408`, `429` or a server
365
+ error for about 30 seconds. For the relay the time each try takes counts too, so a relay that takes the connection and
366
+ never answers is given up on in about 30 seconds as well. What was fetched stays on the relay, and the next run sends it
367
+ again as a new request, so a `track` operation's points can then appear twice.
368
+
369
+ What was checked: [`tests/test_cloud_relay.py`](https://github.com/Ziorentia/Erdigo-sdk/blob/main/python/tests/test_cloud_relay.py) runs the relay against every case in
370
+ [`cloud-relay-cases.json`](https://github.com/Ziorentia/Erdigo-sdk/blob/main/docs/cloud-relay-cases.json), and against the rest of the API: tokens, the order of the
371
+ checks, size limits, whole batches, a full queue, epochs, expiry with a test clock, paging, waiting, slow clients, its
372
+ start-up checks and its log. [`tests/test_cloud_gateway.py`](https://github.com/Ziorentia/Erdigo-sdk/blob/main/python/tests/test_cloud_gateway.py) runs the relay, the gateway
373
+ and the test receiver together: every operation kind, a second run, kinds the person did not allow, the app out of
374
+ reach with and without `--once` (an answer lost before a long outage is sent again with the same sequence number, and
375
+ Ctrl+C and `SIGTERM` stop the gateway while the SDK waits), a proxy in front of the test receiver that loses every
376
+ answer or holds every answer back (given up on with `--once`; lost answers waited out without it; the same request
377
+ with the same number each time), a track paced for longer than `--once` allows, also right after a "not now", which
378
+ is not given up on, the relay out of reach with `--once` (nothing listening,
379
+ server errors, and a relay that never answers), a relay restart, wrong tokens, answers that break the API, and HTTPS
380
+ with a test certificate. CI runs [`scripts/cloud_relay_interop.py`](https://github.com/Ziorentia/Erdigo-sdk/blob/main/python/scripts/cloud_relay_interop.py) against the .NET
381
+ mock on Linux and Windows, and it was run locally against the Swift mock. **Not checked:** a real server behind an
382
+ HTTPS proxy, the released app, a Raspberry Pi, and this gateway with the other editions' relays. No security audit has
383
+ been done.
384
+
385
+ ## Layout
386
+
387
+ | Path | Contents |
388
+ |---|---|
389
+ | `src/erdigo_sdk/` | The library: `noise.py` (the handshakes), `strict_json.py` and `messages.py` (the wire format), `model.py`, `pairing.py`, `client.py`, `store.py`, `private_file.py` and `_windows.py` (DPAPI and access lists), `discovery.py`, and `cli.py` (the tool) |
390
+ | `examples/quickstart.py` | A complete small program |
391
+ | `examples/cloud_relay/` | The [cloud relay example](#cloud-relay-example): `relay.py` and `gateway.py` |
392
+ | `tests/` | Unit, vector and end-to-end tests, with a small scripted receiver in `tests/receiver.py` |
393
+ | `scripts/interop.py` | Pairs with the .NET or Swift mock receiver and writes every item kind to it |
394
+ | `scripts/cloud_relay_interop.py` | Runs the cloud relay example end to end against the .NET or Swift mock receiver |
395
+ | `requirements/` | The exact versions and hashes CI installs |
396
+
397
+ ## Tests
398
+
399
+ From the `python` folder, in a virtual environment:
400
+
401
+ ```bash
402
+ pip install --require-hashes -r requirements/test.txt
403
+ pip install --no-deps --no-build-isolation .
404
+ python -m pytest
405
+ ```
406
+
407
+ The tests use the official Noise vectors and every integration-v1 vector in [`spec/vectors`](https://github.com/Ziorentia/Erdigo-sdk/blob/main/spec/vectors/README.md),
408
+ byte for byte, so run them from a full clone. They also run the SDK and the tool against a small receiver over real TCP,
409
+ including the cases that must fail: a typed code nobody confirmed, a wrong fingerprint, a receiver key spelled two ways,
410
+ low-order keys, every kind of error answer, files others can read, and a code given as an argument. The Windows-only
411
+ tests of DPAPI and access lists run on Windows, and the ones that need a pseudo terminal run on Linux and macOS. Each
412
+ defence the tests cover was also removed in turn to check that its test then fails.
413
+
414
+ To check this edition against another one's mock receiver, build that mock and run, for example:
415
+
416
+ ```bash
417
+ python scripts/interop.py --cwd ../dotnet -- dotnet run --project src/erdigo-send --
418
+ python scripts/interop.py --cwd .. -- swift run erdigo-send
419
+ ```
420
+
421
+ ## What has and has not been checked
422
+
423
+ - The Noise handshakes reproduce the official vectors for `IK`, `XXpsk3` and `NNpsk0`, and the published pairing and
424
+ connection vectors byte for byte. Every request in `messages.json` is accepted or refused with its error code.
425
+ - CI, on Linux and Windows with Python 3.10 and 3.14: the tests, and pairing with the .NET mock and writing every item
426
+ kind to it (two photos, one in several chunks, a two-point track, a move, a delete and delete-all), checked with the
427
+ mock's own list of what it holds. On Linux also a typed code answered `no` and then `yes` on a pseudo terminal, and
428
+ finding the mock through its advertisement.
429
+ - Locally on a Mac (Apple silicon, Python 3.14): the same against the Swift mock.
430
+ - **Not checked:** a real Raspberry Pi or any ARM board, Python 3.11 to 3.13, macOS in CI, discovery on Windows or
431
+ macOS or of a real receiver, and the real Erdigo app, which accepts these connections from version 2.17.23.
432
+ - **No independent security audit has been done.**