dosync 0.4.1__tar.gz → 0.4.2__tar.gz

{dosync-0.4.1 → dosync-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dosync
-Version: 0.4.1
+Version: 0.4.2
 Summary: The semantic layer between AI agents and physical devices
 Author-email: Rodrigo Giuliani <rgiuliani@dosync.dev>
 License-Expression: Apache-2.0
@@ -27,12 +27,16 @@ Requires-Dist: fastapi<1.0,>=0.115.0
 Requires-Dist: uvicorn<1.0,>=0.23.0
 Requires-Dist: pydantic<3.0,>=2.7.0
 Requires-Dist: jsonschema<5.0,>=4.18
+Requires-Dist: bleak>=0.21
+Requires-Dist: pyyaml>=6.0.1
+Requires-Dist: aiohttp>=3.9.0
+Requires-Dist: paho-mqtt>=2.0.0
 Provides-Extra: wiz
 Requires-Dist: pywizlight>=0.5.0; extra == "wiz"
 Provides-Extra: mqtt
 Requires-Dist: paho-mqtt>=2.0.0; extra == "mqtt"
 Provides-Extra: ha
-Requires-Dist: aiohttp>=3.8.0; extra == "ha"
+Requires-Dist: aiohttp>=3.9.0; extra == "ha"
 Provides-Extra: ble
 Requires-Dist: bleak>=0.21; extra == "ble"
 Provides-Extra: sms
@@ -44,7 +48,7 @@ Requires-Dist: mcp>=1.0.0; extra == "mcp"
 Provides-Extra: all
 Requires-Dist: pywizlight>=0.5.0; extra == "all"
 Requires-Dist: paho-mqtt>=2.0.0; extra == "all"
-Requires-Dist: aiohttp>=3.8.0; extra == "all"
+Requires-Dist: aiohttp>=3.9.0; extra == "all"
 Requires-Dist: bleak>=0.21; extra == "all"
 Requires-Dist: twilio>=8.0.0; extra == "all"
 Requires-Dist: pymavlink>=2.4.0; extra == "all"
@@ -57,7 +61,7 @@ Dynamic: license-file
 
 # DoSync Protocol
 
-> The semantic layer between AI agents and physical devices.
+> Governance and accountability for AI that acts on physical devices.
 
 [![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
 [![Protocol](https://img.shields.io/badge/protocol-v0.4-green.svg)](spec/DoSync-SPEC-v0.1.md)
@@ -99,6 +103,65 @@ When the hub receives `"ensure_safety / emergency"`, every registered device fig
 
 ---
 
+## How is this different from what already exists?
+
+A fair question, and the honest answer is that DoSync sits **above** most of what
+it gets compared to, not against it.
+
+| | What it does | What it does not decide |
+|---|---|---|
+| **Matter, Zigbee, MQTT** | Move commands to devices | Which device should act, or whether it should |
+| **W3C Web of Things** (Thing Description) | Describe a device's properties, actions and events, with semantic annotations | Which devices serve a goal, what an operator forbids, or what happened afterwards |
+| **MCP, A2A** | Connect an agent to tools | Anything about a tool being a door lock and the action being irreversible |
+| **DoSync** | Resolve a goal to a plan, constrain it, execute it, and prove what happened | Transport, device description, or agent connectivity — it uses all three |
+
+**Specifically on W3C Web of Things**, since it is the closest and the most
+established: a Thing Description tells you a lock exposes a `lock` action and
+how to invoke it. That is genuinely the right way to describe a device, and
+DoSync does not compete with it. What a description cannot do is decide that a
+lock is one of the things that should respond to *"there is an emergency"*,
+refuse to touch it because this deployment forbids it, arbitrate when two
+intents want it at once, or leave evidence afterwards that survives someone with
+root access. Those are the questions DoSync answers.
+
+**On MCP**: DoSync ships an MCP server. It is a distribution channel, not a
+rival. MCP is how an agent reaches DoSync; DoSync is what happens between the
+agent's goal and a device moving.
+
+### The five things
+
+Everything above reduces to five properties. Each is verifiable in a running
+hub — the numbers below come from the reference deployment, not from a
+brochure:
+
+1. **Explainable resolution.** `GET /v1/intents/{class}/explain` returns which
+   devices were evaluated, which were included, and the score breakdown behind
+   each. The score it reports is the same value the resolver decided with — one
+   computation, not a narration of one.
+2. **Policies the AI cannot route around.** A deployment declares what must not
+   happen; every path to a device is evaluated against it, including direct
+   device actions and the MCP tool. This was not true until we audited our own
+   claim and found the hole.
+3. **A record that resists tampering — and says where it stops.** SHA-256 chain
+   with policy provenance, plus sequence numbers, a head mark and signed
+   exportable checkpoints. What it detects and what it cannot is written down in
+   [the threat model](docs/AUDIT-THREAT-MODEL.md), including the rows that read
+   "not detected".
+4. **Formal arbitration of physical conflict.** A per-device claim state machine
+   with stated invariants ([consistency model §3.1](spec/CONSISTENCY-MODEL.md)), so an
+   emergency and a routine wanting the same device is resolved by rule rather
+   than by timing.
+5. **Failure semantics that do not lie.** `contradicted` (the device said yes,
+   the sensor disagrees) is distinct from `unverifiable` (we could not look), and
+   `likely_powered_off` from `indeterminate`. The system says what it does not
+   know.
+
+None of these is claimed to be unbreakable. Claim 3 in particular has documented
+limits, on purpose: a protocol whose value is honesty cannot make absolute
+security claims and stay coherent.
+
+---
+
 ## Scope and safety boundaries
 
 DoSync coordinates **non-safety-critical systems** — lighting, access, climate, notifications, logging — and produces a tamper-evident record of every action. It is infrastructure for coordination and auditability, not a certified safety system.
@@ -190,10 +253,43 @@ Benchmark (Raspberry Pi 5, Python 3.11.2):
 ### Install and run — five minutes, no hardware
 
 ```bash
-pip install dosync
+pipx install dosync      # recommended
 dosync-hub
 ```
 
+<details>
+<summary><b>"error: externally-managed-environment"?</b> — Raspberry Pi OS, Debian 12+, Ubuntu 23.04+</summary>
+
+Those systems refuse system-wide `pip install` (PEP 668) to stop Python packages
+from breaking the OS. This hits the Raspberry Pi first, which is the most likely
+machine to be running a hub, so it is worth getting right rather than working
+around.
+
+**`pipx` is the correct tool here** and not a workaround: DoSync is an
+application with commands you run, not a library you import into your own code.
+pipx gives it a private environment and still puts `dosync-hub`,
+`dosync-manage` and `dosync-certify` on your PATH.
+
+```bash
+sudo apt install pipx        # once
+pipx ensurepath              # once; open a new shell afterwards
+pipx install dosync
+```
+
+If you are writing Python against DoSync rather than running the hub, a virtual
+environment is the right choice instead:
+
+```bash
+python3 -m venv ~/dosync-env
+~/dosync-env/bin/pip install dosync
+~/dosync-env/bin/dosync-hub
+```
+
+`pip install --break-system-packages dosync` also works and is the one option we
+would not recommend: it installs into the system Python that your OS depends on,
+which is the situation PEP 668 exists to prevent.
+</details>
+
 That is a working hub on `http://127.0.0.1:47200`. It starts with a simulated
 executor, so you can drive the whole protocol — register devices, fire intents,
 read the audit chain — before you own a single smart device.
@@ -228,7 +324,93 @@ evaluated, which it included, and the score breakdown behind each decision.
 Step 4 is the other: every action leaves a SHA-256-chained entry, so what the
 system did is provable after the fact rather than merely logged.
 
-Install only the adapters you need:
+**Discovery works out of the box.** The library that finds Bluetooth devices
+ships in the core install, and the BLE adapter registers itself when it is
+available — because discovery is how you learn what you have. Requiring an extra
+first would be a circle: nobody installs a Bluetooth library before knowing they
+own Bluetooth devices, and nobody can find out without it. A hub with no radio
+loses nothing — the scan reports the transport as unsearchable rather than
+failing — and `pip uninstall bleak` or `DOSYNC_BLE_ENABLED=false` removes it.
+
+**On the adapters that ship with DoSync.** They come in three kinds, visible at
+`GET /v1/adapters`. **Ecosystem** adapters implement open standards — MQTT,
+Matter, BLE, MAVLink, and the Home Assistant bridge, which is the widest door of
+all: anything HA already integrates, DoSync can reach. **Reference** adapters
+(WiZ, Shelly) implement one vendor's product and ship as worked examples of how
+an adapter is written — not as endorsement, partnership, or a promise to track
+anyone's firmware. **Infrastructure** is notifications.
+
+**If your device is not covered, describe it in a file.** A declarative adapter
+is YAML or JSON — no code, no release of DoSync to wait for:
+
+```yaml
+device:
+  id: light-hallway
+  name: Hallway light
+  tags: [light, energy]        # how intents find it
+  emergency_capable: true      # whether an emergency may use it
+
+transport:
+  kind: http
+  base_url: http://192.168.1.40
+
+actions:
+  turn_on:
+    type: turn_on              # what it MEANS to DoSync, not just its name
+    request: { method: POST, path: /light/on }
+```
+
+Drop it in `declarative/` (or set `DOSYNC_DECLARATIVE_DIR`) and restart.
+
+**You do not have to write the first one.** Six worked examples ship with the
+package — a light, an air conditioner, a 3D printer, a television, a floor's
+lighting controller and an industrial conveyor over MQTT — chosen so one of them
+probably resembles what you have:
+
+```bash
+dosync-manage examples        # copies them into declarative/, ready to edit
+```
+
+They are also readable in the repository at
+[`examples/declarative/`](examples/declarative/).
+
+The `type` on each action is the part that matters. A file that only said "POST
+/on turns it on" would let DoSync switch the device and leave it invisible to
+everything else: no intent could select it, no policy could name it, an
+emergency would pass it by.
+
+**What a declarative adapter cannot do**, stated plainly: it speaks HTTP. It
+cannot speak Zigbee, Z-Wave, BLE pairing, an OPC-UA session, or anything needing
+a handshake, session state or a vendor SDK. Those need a code adapter — an
+ecosystem one here, or a third-party package. This format covers most simple
+devices and almost no complex ones.
+
+**If it needs real code — pairing, a session, a vendor SDK — publish a package.**
+DoSync discovers adapters advertised by anything installed alongside it:
+
+```toml
+# in the vendor's pyproject.toml
+[project.entry-points."dosync.adapters"]
+daikin = "dosync_adapter_daikin:DaikinAdapter"
+```
+
+The operator runs `pip install dosync-adapter-daikin` and the hub finds it. No
+pull request here, and no promise from this project to maintain code for
+hardware it has never seen — the publisher answers for their own adapter.
+
+A third-party adapter runs inside the hub with the hub's permissions, so the hub
+says so: it is logged at WARNING when loaded, recorded in the audit chain, and
+reported as `kind: third_party` at `/v1/adapters` regardless of what the plugin
+declares about itself. Where code came from is not the code's to assert.
+
+DoSync does not download an adapter for you: the
+protocol's whole argument is that nothing actuates hardware without a policy and
+a record, and fetching executable code from the internet would put the largest
+possible hole exactly there. Instead, an operator writes a declarative adapter
+for HTTP/MQTT/Modbus devices, or installs a third-party package deliberately.
+
+Install only the CONTROL adapters you need — those follow the opposite rule,
+since you already know which hardware you own:
 
 ```bash
 pip install 'dosync[wiz]'      # Philips WiZ bulbs
@@ -237,6 +419,147 @@ pip install 'dosync[mqtt]'     # MQTT devices
 pip install 'dosync[all]'      # everything
 ```
 
+### Access: token, your own password, or none
+
+The hub prints an API token the first time it starts and stores only a hash of
+it, so it cannot show you that one again. Three ways to deal with that,
+depending on who you are:
+
+```bash
+# 1. Choose your own, like a password — for a person who has to type it
+dosync-manage keys create --token "my-house-2026-kitchen" --label dashboard
+
+# 2. Let it generate one — for a program that will store it
+dosync-manage keys create --label my-integration
+
+# 3. Turn authentication off entirely
+DOSYNC_AUTH=false dosync-hub
+```
+
+**Option 3 is legitimate and not a trap door.** On a home network, behind a
+router, with no port forwarding, requiring a token protects against nobody who
+is not already inside your house. It is the wrong default for a clinic and a
+reasonable choice for a workshop, so DoSync provides it plainly instead of
+pretending everyone has the same threat model. What it is not suitable for is
+any hub reachable from outside its own network.
+
+Tokens are checked without rate limiting or lockout, so a chosen one must be at
+least 12 characters and a passphrase of several words is better than a short
+clever string. Existing keys: `dosync-manage keys list` (previews only — they
+are hashed), `dosync-manage keys revoke <preview>`, `dosync-manage keys reset`.
+
+### Access: a password you choose, or none at all
+
+The hub prints a token on first start and stores only a hash of it, so it cannot
+show you that one again. You are not stuck with it.
+
+**From the dashboard** (the ⚙ button, once connected): set a password of your
+choosing, or turn the token requirement off entirely. No shell, no unit file.
+
+**From a terminal**, if you prefer:
+
+```bash
+# Choose your own — for a person who has to type it
+dosync-manage keys create --token "my-house-2026-kitchen" --label dashboard
+
+# Let it generate one — for a program that will store it
+dosync-manage keys create --label my-integration
+
+# Start with no authentication at all
+DOSYNC_AUTH=false dosync-hub
+```
+
+**Running without a token is a legitimate choice, not a trap door.** On a home
+network, behind a router, with no port forwarding, a token protects against
+nobody who is not already inside your house. It is the wrong default for a
+clinic and an unnecessary obstacle for a workshop, so DoSync offers it plainly
+rather than assuming everyone shares one threat model. It is not suitable for
+any hub reachable from outside its own network.
+
+Two things worth knowing:
+
+- **`DOSYNC_AUTH` in the environment wins.** If it is set in your service
+  configuration, the dashboard will tell you so and refuse to override it — a
+  click in a browser should not quietly undo what the machine was told to do.
+- **Changing access is recorded.** Setting a password or turning authentication
+  off appends to the audit chain, so "when did this hub become open, and who did
+  it" has an answer. The token value itself is never written there.
+
+A chosen password must be at least 12 characters, and a passphrase of several
+words is better than a short clever string: a bearer token is checked with no
+rate limiting and no lockout, so it is guessed offline at full speed.
+
+Existing keys: `dosync-manage keys list` (previews only — they are hashed),
+`keys revoke <preview>`, `keys reset`.
+
+### Hardware that cannot do TLS
+
+A sensor running a year on a coin cell cannot perform a TLS handshake — it costs
+more battery than a month of operation. Such a device can still report liveness,
+signed rather than encrypted:
+
+```bash
+DOSYNC_LIGHTWEIGHT_HEARTBEAT=true dosync-hub
+```
+
+`POST /v1/heartbeat/signed` accepts a heartbeat authenticated by HMAC over the
+device's provisioning token. It is **off by default**, and it is worth knowing
+exactly what it trades before turning it on: the channel provides message
+authenticity and replay resistance, and **no confidentiality** — the device id,
+timestamp and report travel readable. Devices using it are marked
+`report_channel: signed_plaintext` so they are distinguishable from ones on mTLS.
+
+That trade is defensible for a heartbeat and would not be for an action: a
+heartbeat is positive signal only, so a forged one cannot switch anything on.
+The attack it invites is replay — repeating a captured message to keep a failed
+device reporting healthy — and that is closed. See spec §7.10 and
+[the threat model](docs/AUDIT-THREAT-MODEL.md).
+
+### TLS, and why your browser says "Not secure"
+
+`bash setup_pki.sh` creates a private certificate authority in `certs/` and
+issues the hub a certificate from it. Start the hub with those files and traffic
+is encrypted:
+
+```bash
+dosync-hub --host 0.0.0.0 &      # or with uvicorn's --ssl-keyfile / --ssl-certfile
+```
+
+Your browser will then show **"Not secure"** with `https` struck through. This
+is expected and it does **not** mean the connection is unencrypted. It means the
+browser does not recognise the authority that signed the certificate — which is
+you. A public CA cannot issue a certificate for `192.168.x.x`, so a hub on a
+private network is always in this position.
+
+Two honest options:
+
+**Accept the warning.** Click through it. The connection is encrypted; what is
+missing is a third party vouching that the server is who it claims. On your own
+LAN, where you set up the hub yourself, that is a much smaller gap than it looks.
+
+**Trust your own CA, and the warning goes away** — on the machines you choose:
+
+```bash
+# macOS
+sudo security add-trusted-cert -d -r trustRoot \
+  -k /Library/Keychains/System.keychain certs/ca.crt
+
+# Linux (Debian/Ubuntu)
+sudo cp certs/ca.crt /usr/local/share/ca-certificates/dosync-ca.crt
+sudo update-ca-certificates
+
+# Windows (PowerShell, as Administrator)
+Import-Certificate -FilePath ca.crt -CertStoreLocation Cert:\LocalMachine\Root
+```
+
+Copy `certs/ca.crt` from the hub first — it is the only file you need, and it
+contains no secret. The hub's private key (`certs/hub.key`) never leaves the
+hub.
+
+**What the warning does mean.** If you see it on a hub you did not set up, or on
+a network you do not control, do not click through — that is exactly the case
+the warning exists for.
+
 ### Docker
 
 ```bash