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.
- erdigo_sdk-1.0.0/LICENSE +21 -0
- erdigo_sdk-1.0.0/MANIFEST.in +2 -0
- erdigo_sdk-1.0.0/PKG-INFO +432 -0
- erdigo_sdk-1.0.0/README.md +405 -0
- erdigo_sdk-1.0.0/pyproject.toml +48 -0
- erdigo_sdk-1.0.0/setup.cfg +4 -0
- erdigo_sdk-1.0.0/src/erdigo_sdk/__init__.py +50 -0
- erdigo_sdk-1.0.0/src/erdigo_sdk/__main__.py +7 -0
- erdigo_sdk-1.0.0/src/erdigo_sdk/_windows.py +254 -0
- erdigo_sdk-1.0.0/src/erdigo_sdk/cli.py +585 -0
- erdigo_sdk-1.0.0/src/erdigo_sdk/client.py +608 -0
- erdigo_sdk-1.0.0/src/erdigo_sdk/discovery.py +155 -0
- erdigo_sdk-1.0.0/src/erdigo_sdk/errors.py +118 -0
- erdigo_sdk-1.0.0/src/erdigo_sdk/identity.py +78 -0
- erdigo_sdk-1.0.0/src/erdigo_sdk/messages.py +700 -0
- erdigo_sdk-1.0.0/src/erdigo_sdk/model.py +399 -0
- erdigo_sdk-1.0.0/src/erdigo_sdk/noise.py +420 -0
- erdigo_sdk-1.0.0/src/erdigo_sdk/pairing.py +203 -0
- erdigo_sdk-1.0.0/src/erdigo_sdk/private_file.py +223 -0
- erdigo_sdk-1.0.0/src/erdigo_sdk/protocol.py +120 -0
- erdigo_sdk-1.0.0/src/erdigo_sdk/store.py +364 -0
- erdigo_sdk-1.0.0/src/erdigo_sdk/stream.py +201 -0
- erdigo_sdk-1.0.0/src/erdigo_sdk/strict_json.py +439 -0
- erdigo_sdk-1.0.0/src/erdigo_sdk/terminal.py +135 -0
- erdigo_sdk-1.0.0/src/erdigo_sdk.egg-info/PKG-INFO +432 -0
- erdigo_sdk-1.0.0/src/erdigo_sdk.egg-info/SOURCES.txt +28 -0
- erdigo_sdk-1.0.0/src/erdigo_sdk.egg-info/dependency_links.txt +1 -0
- erdigo_sdk-1.0.0/src/erdigo_sdk.egg-info/entry_points.txt +2 -0
- erdigo_sdk-1.0.0/src/erdigo_sdk.egg-info/requires.txt +9 -0
- erdigo_sdk-1.0.0/src/erdigo_sdk.egg-info/top_level.txt +1 -0
erdigo_sdk-1.0.0/LICENSE
ADDED
|
@@ -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,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.**
|