dosync 0.8.0__tar.gz → 0.9.0__tar.gz

{dosync-0.8.0 → dosync-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dosync
-Version: 0.8.0
+Version: 0.9.0
 Summary: The semantic layer between AI agents and physical devices
 Author-email: Rodrigo Giuliani <rgiuliani@dosync.dev>
 License-Expression: Apache-2.0
@@ -271,10 +271,14 @@ its first step.
 ### Install and run — five minutes, no hardware
 
 ```bash
-pipx install dosync      # recommended
+pipx install "dosync[mcp]"      # recommended; [mcp] adds the agent connection
 dosync-hub
 ```
 
+Prefer a container, or run Home Assistant? See [Docker — one
+command](#docker--one-command) and [Home Assistant add-on](#home-assistant-add-on):
+all three end in the same dashboard.
+
 <details>
 <summary><b>On Windows</b> — pipx is not installed with Python there</summary>
 
@@ -316,6 +320,15 @@ Paste the API key the hub printed on startup, press **Scan**, and the hub
 searches every transport it can reach — WiFi broadcast, mDNS, SSDP, Bluetooth —
 and shows what answered. Name anything you want to keep and it is adopted.
 
+**Governance is on the same page.** **⏸** lists actions an agent asked for
+that you marked as needing a person — confirm or deny them there. **Governance**
+is where you say where each device is (`kitchen`, `plant-1/line-3`,
+`ward-2/room-12` — any path), what it does in an emergency, and which actions
+must wait for you. Releasing a held action or changing those marks takes the
+*operator credential* (`DOSYNC_OPERATOR_TOKEN`, set where the hub starts), which
+your agent never holds. **Agent** connects the agent you use (see
+[Connecting an agent](#connecting-an-agent)).
+
 **Start here.** Discovering and adopting a device needs no terminal and no
 JSON: a 3D printer, a television and a Bluetooth sensor were adopted this way
 on the reference deployment without a line being typed. The API calls below are
@@ -672,14 +685,38 @@ hub.
 a network you do not control, do not click through — that is exactly the case
 the warning exists for.
 
-### Docker
+### Docker — one command
 
 ```bash
-docker run -p 47200:47200 dosync/hub        # published image
-# or, from a clone:
-docker compose up
+docker run -d --name dosync -p 47200:47200 -v dosync-data:/data \
+  ghcr.io/giulianireg-spec/dosync-protocol:latest
+docker logs dosync        # the hub's token, printed on first start
 ```
 
+Then open `http://localhost:47200`. The image is built for amd64 and arm64 (a
+Raspberry Pi), includes the MCP server (`docker exec dosync dosync-mcp
+--print-config`), keeps its database, keys and audit chain in the `/data`
+volume, and has **authentication on**: a container listens on the network. On
+Linux add `--network host` so discovery (mDNS, SSDP, broadcast) sees your
+network — a bridged container only sees itself. Settings are the same
+environment variables as anywhere (`-e DOSYNC_OPERATOR_TOKEN=…`), and a
+`policies.json` placed in the volume is loaded. From a clone, `docker compose up`
+runs a demo with sample devices.
+
+### Home Assistant add-on
+
+In Home Assistant: **Settings → Add-ons → Add-on store → ⋮ → Repositories**, add
+
+```
+https://github.com/giulianireg-spec/dosync-protocol
+```
+
+install **DoSync**, start it, read the token in its **Log** tab and press **Open
+web UI**. It runs the same image, and its Home Assistant bridge connects through
+the Supervisor — no long-lived token to create. Your entities appear as devices,
+governed by your rules; the operator token, who configures, and the confirmation
+timeout are options of the add-on.
+
 ### From source (development)
 
 ```bash
@@ -793,6 +830,27 @@ test, so it is named rather than recommended.
 
 ## Connecting an agent
 
+**The short way — no paths to work out.** Install the MCP part once, then let
+DoSync write your agent's configuration:
+
+```bash
+pipx install "dosync[mcp]"          # or, if DoSync is already installed:
+                                    #    pipx inject dosync "mcp>=1.27.0,<2.0"
+dosync-mcp --check --token <your token>          # says what is missing, in words
+dosync-mcp --print-config --token <your token>   # the block to paste into your agent
+```
+
+Or open the dashboard and press **Agent**: it shows the same block, with this
+hub's address and your token already filled in, and where common agents keep
+the file. Any MCP client works — Claude Desktop, Claude Code, Cursor or another;
+the protocol does not pick your agent. When the agent runs on a different
+computer from the hub, install DoSync there too and add `--hub-url
+http://<hub address>:47200`. CI runs exactly this path (pipx → hub → dashboard →
+agent) on Linux and macOS on every change.
+
+Everything below explains what that command writes, for when you want to do it
+by hand.
+
 This page has said "MCP" a dozen times — a badge at the top, a section on why
 MCP is the channel rather than the rival, a drone that flew a mission through
 it — and never once explained how to connect an agent. This is that.
@@ -952,6 +1010,58 @@ the other end.
 
 ---
 
+### What an agent can do — and how to change it
+
+Out of the box, an agent connected through MCP can do three things:
+
+- **Pursue a goal** — `dosync_fire_intent` with a class (`ensure_safety`,
+  `notify`, … or one your deployment registers) and let the hub choose the
+  devices.
+- **Choose the devices itself** — the same tool with `proposed_actions`; the
+  hub runs only the proposals that pass its rules.
+- **Operate a named device** — `dosync_control_device`: *"turn off the hall
+  light"*, *"stop line 2"*, *"fly the drone to these coordinates"*. It fires the
+  universal class `operate_device`, which grants any action the device declares,
+  so nothing has to be configured first.
+
+All three are checked by the hub before anything moves. The device must declare
+the action; a place the agent names confines it; no device receives two
+opposite actions (`lock`/`unlock`, `turn_on`/`turn_off`, …); in an emergency, a
+device that declared its emergency actions does only those; your policies
+apply; and every action — and every refusal, with its reason — is in the audit
+log.
+
+What is **not** narrowed by default is *authority*: `operate_device` grants any
+action a device declares. You decide how much of that an agent gets:
+
+| You want | Do this |
+|---|---|
+| Agents to act only through goals you defined | Block the class in your policy file: `{"type": "block_intent", "intent_classes": ["operate_device"], "reason": "Agents act through our goals"}` |
+| Agents to keep their hands off some devices | `{"type": "device_exclusion", "intent_classes": ["operate_device"], "excluded_device_ids": ["front-door-lock"]}` |
+| Your own scripts to call one device with no intent around it | `DOSYNC_DIRECT_CONTROL=operator` and `DOSYNC_OPERATOR_TOKEN=<secret>`; send it as `X-DoSync-Operator-Token`. **Never give this token to an agent.** |
+| The raw path open, for development | `DOSYNC_DIRECT_CONTROL=on` — the hub says so in `/v1/status` |
+
+(Policy files are JSON with `"version": 1` and a `"policies"` list, loaded from
+`DOSYNC_POLICIES`.)
+
+Devices described by a **W3C WoT Thing Description** join the same way: `POST
+/v1/things` with the TD (and, as the operator, the place it is in). The hub maps
+its actions, reports how it mapped each one, and governs it like any other
+device — see spec §5.9.
+
+And the other way: **every device the hub governs is published as a W3C WoT
+Thing Description**, so any WoT consumer — one that has never heard of DoSync —
+can find and use it. `GET /.well-known/wot` describes the directory, `GET
+/v1/things` lists the TDs, and each action's form points at the hub, never at the
+device: invoking it runs through the same rules as an agent's request (an action
+you marked comes back `202 held_for_confirmation` and waits for you in ⏸).
+Tested in CI with an independent consumer, Eclipse Thingweb node-wot — see spec
+§5.10.
+
+The raw HTTP path, `POST /v1/device/action`, is **closed by default**. It names
+a device and an action with no intent around it, so the hub's guarantees cannot
+apply to it; it exists for an operator, not an agent.
+
 ## What's built today
 
 | Component | Status |
@@ -961,7 +1071,8 @@ the other end.
 | Web dashboard | ✅ |
 | API key authentication + SHA-256 audit log | ✅ |
 | Capability-based resolver | ✅ |
-| Certification CLI — Basic 10 · Standard 33 · Emergency 44 · Conformance 69, each run in CI against a live hub (signed reports) | ✅ |
+| Certification CLI — Basic 10 · Standard 33 · Emergency 44 · Conformance 72, each run in CI against a live hub (signed reports) | ✅ |
+| W3C WoT: import Thing Descriptions, publish governed ones, WoT Discovery; interop tested with node-wot | ✅ |
 | Philips WiZ adapter (UDP local) | ✅ |
 | Home Assistant bridge (10 domains) | ✅ |
 | Native MCP server (Claude, ChatGPT, any LLM) | ✅ |
@@ -1014,8 +1125,8 @@ python3 certify.py --host <hub-ip> --port 47200 --tier standard
 
 | Language | Location | Author | Certification |
 |---|---|---|---|
-| Python (reference) | `server.py` | this project | Conformance 69/69 ✅ (every tier, in CI) |
-| Node.js (companion) | [giulianireg-spec/dosync-node](https://github.com/giulianireg-spec/dosync-node) | this project | Standard 33/33, against the v0.3 suite — re-validation against the current 69-check suite pending |
+| Python (reference) | `server.py` | this project | Conformance 70/70 ✅ (every tier, in CI) |
+| Node.js (companion) | [giulianireg-spec/dosync-node](https://github.com/giulianireg-spec/dosync-node) | this project | Standard 33/33, against the v0.3 suite — re-validation against the current 70-check suite pending |
 
 The Node.js implementation is a **companion** port that validates the protocol
 is implementable in a second language against the same certification suite —
@@ -1051,6 +1162,7 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for development workflow, including the C
 ## Specification
 
 - [spec/DoSync-SPEC-v0.1.md](spec/DoSync-SPEC-v0.1.md) — full protocol specification
+- [spec/SAMUEL-SPEC-v0.2.md](spec/SAMUEL-SPEC-v0.2.md) — **SAMUEL**, Standard for Agent Mediation Under Enforceable Limits: what an AI agent may do to physical devices, within limits the operator sets and the hub enforces — nine guarantees independent of how devices are described (DoSync manifests, WoT Thing Descriptions), every refusal reason, and the certification checks that show conformance. DoSync is its reference implementation
 - [spec/RESOLVER-SPEC-v0.3.md](spec/RESOLVER-SPEC-v0.3.md) — resolver interface + external resolver protocol
 - [DESIGN-PRINCIPLES.md](DESIGN-PRINCIPLES.md) — architectural decisions and rationale
 - [COMPATIBILITY.md](docs/COMPATIBILITY.md) — backward compatibility guarantees

{dosync-0.8.0 → dosync-0.9.0}/README.md

@@ -205,10 +205,14 @@ its first step.
 ### Install and run — five minutes, no hardware
 
 ```bash
-pipx install dosync      # recommended
+pipx install "dosync[mcp]"      # recommended; [mcp] adds the agent connection
 dosync-hub
 ```
 
+Prefer a container, or run Home Assistant? See [Docker — one
+command](#docker--one-command) and [Home Assistant add-on](#home-assistant-add-on):
+all three end in the same dashboard.
+
 <details>
 <summary><b>On Windows</b> — pipx is not installed with Python there</summary>
 
@@ -250,6 +254,15 @@ Paste the API key the hub printed on startup, press **Scan**, and the hub
 searches every transport it can reach — WiFi broadcast, mDNS, SSDP, Bluetooth —
 and shows what answered. Name anything you want to keep and it is adopted.
 
+**Governance is on the same page.** **⏸** lists actions an agent asked for
+that you marked as needing a person — confirm or deny them there. **Governance**
+is where you say where each device is (`kitchen`, `plant-1/line-3`,
+`ward-2/room-12` — any path), what it does in an emergency, and which actions
+must wait for you. Releasing a held action or changing those marks takes the
+*operator credential* (`DOSYNC_OPERATOR_TOKEN`, set where the hub starts), which
+your agent never holds. **Agent** connects the agent you use (see
+[Connecting an agent](#connecting-an-agent)).
+
 **Start here.** Discovering and adopting a device needs no terminal and no
 JSON: a 3D printer, a television and a Bluetooth sensor were adopted this way
 on the reference deployment without a line being typed. The API calls below are
@@ -606,14 +619,38 @@ hub.
 a network you do not control, do not click through — that is exactly the case
 the warning exists for.
 
-### Docker
+### Docker — one command
 
 ```bash
-docker run -p 47200:47200 dosync/hub        # published image
-# or, from a clone:
-docker compose up
+docker run -d --name dosync -p 47200:47200 -v dosync-data:/data \
+  ghcr.io/giulianireg-spec/dosync-protocol:latest
+docker logs dosync        # the hub's token, printed on first start
 ```
 
+Then open `http://localhost:47200`. The image is built for amd64 and arm64 (a
+Raspberry Pi), includes the MCP server (`docker exec dosync dosync-mcp
+--print-config`), keeps its database, keys and audit chain in the `/data`
+volume, and has **authentication on**: a container listens on the network. On
+Linux add `--network host` so discovery (mDNS, SSDP, broadcast) sees your
+network — a bridged container only sees itself. Settings are the same
+environment variables as anywhere (`-e DOSYNC_OPERATOR_TOKEN=…`), and a
+`policies.json` placed in the volume is loaded. From a clone, `docker compose up`
+runs a demo with sample devices.
+
+### Home Assistant add-on
+
+In Home Assistant: **Settings → Add-ons → Add-on store → ⋮ → Repositories**, add
+
+```
+https://github.com/giulianireg-spec/dosync-protocol
+```
+
+install **DoSync**, start it, read the token in its **Log** tab and press **Open
+web UI**. It runs the same image, and its Home Assistant bridge connects through
+the Supervisor — no long-lived token to create. Your entities appear as devices,
+governed by your rules; the operator token, who configures, and the confirmation
+timeout are options of the add-on.
+
 ### From source (development)
 
 ```bash
@@ -727,6 +764,27 @@ test, so it is named rather than recommended.
 
 ## Connecting an agent
 
+**The short way — no paths to work out.** Install the MCP part once, then let
+DoSync write your agent's configuration:
+
+```bash
+pipx install "dosync[mcp]"          # or, if DoSync is already installed:
+                                    #    pipx inject dosync "mcp>=1.27.0,<2.0"
+dosync-mcp --check --token <your token>          # says what is missing, in words
+dosync-mcp --print-config --token <your token>   # the block to paste into your agent
+```
+
+Or open the dashboard and press **Agent**: it shows the same block, with this
+hub's address and your token already filled in, and where common agents keep
+the file. Any MCP client works — Claude Desktop, Claude Code, Cursor or another;
+the protocol does not pick your agent. When the agent runs on a different
+computer from the hub, install DoSync there too and add `--hub-url
+http://<hub address>:47200`. CI runs exactly this path (pipx → hub → dashboard →
+agent) on Linux and macOS on every change.
+
+Everything below explains what that command writes, for when you want to do it
+by hand.
+
 This page has said "MCP" a dozen times — a badge at the top, a section on why
 MCP is the channel rather than the rival, a drone that flew a mission through
 it — and never once explained how to connect an agent. This is that.
@@ -886,6 +944,58 @@ the other end.
 
 ---
 
+### What an agent can do — and how to change it
+
+Out of the box, an agent connected through MCP can do three things:
+
+- **Pursue a goal** — `dosync_fire_intent` with a class (`ensure_safety`,
+  `notify`, … or one your deployment registers) and let the hub choose the
+  devices.
+- **Choose the devices itself** — the same tool with `proposed_actions`; the
+  hub runs only the proposals that pass its rules.
+- **Operate a named device** — `dosync_control_device`: *"turn off the hall
+  light"*, *"stop line 2"*, *"fly the drone to these coordinates"*. It fires the
+  universal class `operate_device`, which grants any action the device declares,
+  so nothing has to be configured first.
+
+All three are checked by the hub before anything moves. The device must declare
+the action; a place the agent names confines it; no device receives two
+opposite actions (`lock`/`unlock`, `turn_on`/`turn_off`, …); in an emergency, a
+device that declared its emergency actions does only those; your policies
+apply; and every action — and every refusal, with its reason — is in the audit
+log.
+
+What is **not** narrowed by default is *authority*: `operate_device` grants any
+action a device declares. You decide how much of that an agent gets:
+
+| You want | Do this |
+|---|---|
+| Agents to act only through goals you defined | Block the class in your policy file: `{"type": "block_intent", "intent_classes": ["operate_device"], "reason": "Agents act through our goals"}` |
+| Agents to keep their hands off some devices | `{"type": "device_exclusion", "intent_classes": ["operate_device"], "excluded_device_ids": ["front-door-lock"]}` |
+| Your own scripts to call one device with no intent around it | `DOSYNC_DIRECT_CONTROL=operator` and `DOSYNC_OPERATOR_TOKEN=<secret>`; send it as `X-DoSync-Operator-Token`. **Never give this token to an agent.** |
+| The raw path open, for development | `DOSYNC_DIRECT_CONTROL=on` — the hub says so in `/v1/status` |
+
+(Policy files are JSON with `"version": 1` and a `"policies"` list, loaded from
+`DOSYNC_POLICIES`.)
+
+Devices described by a **W3C WoT Thing Description** join the same way: `POST
+/v1/things` with the TD (and, as the operator, the place it is in). The hub maps
+its actions, reports how it mapped each one, and governs it like any other
+device — see spec §5.9.
+
+And the other way: **every device the hub governs is published as a W3C WoT
+Thing Description**, so any WoT consumer — one that has never heard of DoSync —
+can find and use it. `GET /.well-known/wot` describes the directory, `GET
+/v1/things` lists the TDs, and each action's form points at the hub, never at the
+device: invoking it runs through the same rules as an agent's request (an action
+you marked comes back `202 held_for_confirmation` and waits for you in ⏸).
+Tested in CI with an independent consumer, Eclipse Thingweb node-wot — see spec
+§5.10.
+
+The raw HTTP path, `POST /v1/device/action`, is **closed by default**. It names
+a device and an action with no intent around it, so the hub's guarantees cannot
+apply to it; it exists for an operator, not an agent.
+
 ## What's built today
 
 | Component | Status |
@@ -895,7 +1005,8 @@ the other end.
 | Web dashboard | ✅ |
 | API key authentication + SHA-256 audit log | ✅ |
 | Capability-based resolver | ✅ |
-| Certification CLI — Basic 10 · Standard 33 · Emergency 44 · Conformance 69, each run in CI against a live hub (signed reports) | ✅ |
+| Certification CLI — Basic 10 · Standard 33 · Emergency 44 · Conformance 72, each run in CI against a live hub (signed reports) | ✅ |
+| W3C WoT: import Thing Descriptions, publish governed ones, WoT Discovery; interop tested with node-wot | ✅ |
 | Philips WiZ adapter (UDP local) | ✅ |
 | Home Assistant bridge (10 domains) | ✅ |
 | Native MCP server (Claude, ChatGPT, any LLM) | ✅ |
@@ -948,8 +1059,8 @@ python3 certify.py --host <hub-ip> --port 47200 --tier standard
 
 | Language | Location | Author | Certification |
 |---|---|---|---|
-| Python (reference) | `server.py` | this project | Conformance 69/69 ✅ (every tier, in CI) |
-| Node.js (companion) | [giulianireg-spec/dosync-node](https://github.com/giulianireg-spec/dosync-node) | this project | Standard 33/33, against the v0.3 suite — re-validation against the current 69-check suite pending |
+| Python (reference) | `server.py` | this project | Conformance 70/70 ✅ (every tier, in CI) |
+| Node.js (companion) | [giulianireg-spec/dosync-node](https://github.com/giulianireg-spec/dosync-node) | this project | Standard 33/33, against the v0.3 suite — re-validation against the current 70-check suite pending |
 
 The Node.js implementation is a **companion** port that validates the protocol
 is implementable in a second language against the same certification suite —
@@ -985,6 +1096,7 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for development workflow, including the C
 ## Specification
 
 - [spec/DoSync-SPEC-v0.1.md](spec/DoSync-SPEC-v0.1.md) — full protocol specification
+- [spec/SAMUEL-SPEC-v0.2.md](spec/SAMUEL-SPEC-v0.2.md) — **SAMUEL**, Standard for Agent Mediation Under Enforceable Limits: what an AI agent may do to physical devices, within limits the operator sets and the hub enforces — nine guarantees independent of how devices are described (DoSync manifests, WoT Thing Descriptions), every refusal reason, and the certification checks that show conformance. DoSync is its reference implementation
 - [spec/RESOLVER-SPEC-v0.3.md](spec/RESOLVER-SPEC-v0.3.md) — resolver interface + external resolver protocol
 - [DESIGN-PRINCIPLES.md](DESIGN-PRINCIPLES.md) — architectural decisions and rationale
 - [COMPATIBILITY.md](docs/COMPATIBILITY.md) — backward compatibility guarantees

{dosync-0.8.0 → dosync-0.9.0}/dosync/__init__.py

@@ -13,5 +13,5 @@ The two numbers move independently on purpose:
   __version__           this implementation of the hub  (semver)
   __protocol_version__  the wire contract other implementations must match
 """
-__version__ = "0.8.0"
+__version__ = "0.9.0"
 __protocol_version__ = "0.5"

dosync-0.9.0/dosync/adapters/wot.py

@@ -0,0 +1,136 @@
+"""Execute the actions of imported WoT Things through their TD's HTTP forms.
+
+A Thing imported by dosync/wot_import.py carries, in its adapter_config, each
+governed action's affordance: an action (invokeaction) or a writable property
+(writeproperty), with the forms of its TD. This adapter performs them with the
+WoT HTTP binding defaults -- POST to invoke an action, PUT to write a property,
+GET to read one, JSON bodies -- after the hub has already decided, under its
+guarantees and the operator's policies, that the action may run.
+
+Only HTTP(S) forms are executed. A Thing whose TD offers only CoAP or MQTT forms
+is imported and governed, and its actions are refused here with that reason,
+rather than pretended. Security: ``nosec`` is assumed unless the operator gives
+a bearer token for the Thing in adapter_config["bearer_token_env"] (the name of
+an environment variable, never the token itself).
+"""
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+import re
+import urllib.error
+import urllib.request
+from urllib.parse import quote
+
+from . import DoSyncAdapter
+from ..models import ActionResult
+
+
+_TEMPLATE = re.compile(r"\{([?&/#+.;]?)([^}]*)\}")
+
+
+def expand(href: str, params: dict) -> tuple[str, dict]:
+    """Expand the RFC 6570 templates TD forms use for uriVariables -- ``{var}``
+    in a path and ``{?a,b}`` / ``{&a}`` in a query -- from the action's params.
+    Variables not given are dropped; the params used are removed from the body.
+    Found against node-wot's own example Thing: its counter's form is
+    ``.../actions/increment{?step}``, and the literal template is a 404."""
+    rest = dict(params)
+
+    def fill(m):
+        op, names = m.group(1), [n.strip() for n in m.group(2).split(",") if n.strip()]
+        given = [(n, rest.pop(n)) for n in names if n in rest]
+        if op in ("?", "&"):
+            if not given:
+                return ""
+            q = "&".join(f"{quote(str(n))}={quote(str(v))}" for n, v in given)
+            return ("?" if op == "?" else "&") + q
+        return ",".join(quote(str(v), safe="") for _, v in given)
+    return _TEMPLATE.sub(fill, href), rest
+
+
+def _http_form(forms: list[dict]) -> dict | None:
+    return next((f for f in forms if str(f.get("href", "")).startswith(("http://", "https://"))), None)
+
+
+def _body_for(affordance: dict, params: dict):
+    if affordance["kind"] == "property":
+        return params.get("value", next(iter(params.values()), None)) if params else None
+    schema = affordance.get("input") or {}
+    if not params:
+        return None
+    if isinstance(schema, dict) and schema.get("type") not in (None, "object") and len(params) == 1:
+        return next(iter(params.values()))
+    return params
+
+
+class WotHttpAdapter(DoSyncAdapter):
+    def __init__(self, hub=None, timeout: float = 10.0):
+        self._hub = hub
+        self._timeout = timeout
+
+    @property
+    def adapter_name(self) -> str:
+        return "wot"
+
+    async def connect(self, config) -> bool:
+        return True
+
+    def _config(self, device_id: str) -> dict:
+        device = self._hub.registry.get(device_id) if self._hub else None
+        return dict(getattr(device, "adapter_config", None) or {})
+
+    def _request(self, method: str, url: str, body, config: dict):
+        data = None if body is None else json.dumps(body).encode()
+        req = urllib.request.Request(url, data=data, method=method)
+        if data is not None:
+            req.add_header("Content-Type", "application/json")
+        env = config.get("bearer_token_env")
+        if env and os.environ.get(env):
+            req.add_header("Authorization", f"Bearer {os.environ[env]}")
+        with urllib.request.urlopen(req, timeout=self._timeout) as resp:
+            text = resp.read().decode(errors="replace")
+            return resp.status, text
+
+    async def execute(self, action, urgency) -> ActionResult:
+        config = self._config(action.device_id)
+        if action.action == "read_sensors":
+            readings, errors = {}, []
+            for st, spec in (config.get("sensors") or {}).items():
+                form = _http_form(spec.get("forms") or [])
+                if not form:
+                    continue
+                try:
+                    status, text = await asyncio.to_thread(self._request, form.get("method") or "GET",
+                                                           expand(form["href"], {})[0], None, config)
+                    readings[st] = json.loads(text) if text else None
+                except Exception as e:
+                    errors.append(f"{st}: {type(e).__name__}: {e}")
+            return ActionResult(device_id=action.device_id, action=action.action, success=not errors,
+                                response={"readings": readings}, error="; ".join(errors) or None)
+        affordance = (config.get("affordances") or {}).get(action.action)
+        if not affordance:
+            return ActionResult(device_id=action.device_id, action=action.action, success=False,
+                                error=f"the Thing's TD has no affordance for '{action.action}'")
+        form = _http_form(affordance.get("forms") or [])
+        if not form:
+            return ActionResult(device_id=action.device_id, action=action.action, success=False,
+                                error="the Thing's TD offers no HTTP form for this affordance "
+                                      "(only HTTP is executed; the action is governed but not run)")
+        method = form.get("method") or ("PUT" if affordance["kind"] == "property" else "POST")
+        url, rest = expand(form["href"], dict(action.params or {}))
+        body = _body_for(affordance, rest)
+        try:
+            status, text = await asyncio.to_thread(self._request, method, url, body, config)
+            return ActionResult(device_id=action.device_id, action=action.action, success=200 <= status < 300,
+                                response={"status": status, "body": text[:500]})
+        except urllib.error.HTTPError as e:
+            return ActionResult(device_id=action.device_id, action=action.action, success=False,
+                                error=f"HTTP {e.code}: {e.read().decode(errors='replace')[:200]}")
+        except Exception as e:
+            return ActionResult(device_id=action.device_id, action=action.action, success=False,
+                                error=f"{type(e).__name__}: {e}")
+
+    async def get_state(self, device_id: str) -> dict | None:
+        return None

{dosync-0.8.0 → dosync-0.9.0}/dosync/auth.py

@@ -96,6 +96,14 @@ class AuthManager:
                     "offline at full speed.")
         else:
             token = secrets.token_urlsafe(32)
+        operator = os.environ.get("DOSYNC_OPERATOR_TOKEN", "")
+        if operator and secrets.compare_digest(token, operator):
+            # H5: an agent key equal to the operator credential would hand the
+            # agent the operator's authority (SAMUEL §3: they MUST differ).
+            raise ValueError(
+                "That value is this hub's operator credential. An agent key must be "
+                "different: whoever holds the operator credential releases held "
+                "actions, and the agent must not be able to.")
         key_hash = hash_token(token)
         self.db.save_api_key(key_hash, label)
         log.info("New API key generated: label='%s'", label)