tolpo 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 signerless
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,298 @@
-# Temporary Holding Version
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/signerless/tolpo/main/assets/logo-dark.svg">
+    <img alt="tolpo" src="https://raw.githubusercontent.com/signerless/tolpo/main/assets/logo-light.svg" width="280">
+  </picture>
+</p>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<p align="center"><strong>Local-first control of TP-Link Tapo smart-home devices for AI agents.</strong></p>
+
+<p align="center">
+
+[![CI](https://github.com/signerless/tolpo/actions/workflows/ci.yml/badge.svg)](https://github.com/signerless/tolpo/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/signerless/tolpo/blob/main/LICENSE)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/downloads/)
+
+</p>
+
+`tolpo` turns the Tapo devices on your network into a single interface that an AI agent, or
+your own code, can read and control. It talks to each device directly over the LAN through the open
+source [python-kasa](https://github.com/python-kasa/python-kasa) library, so no request ever leaves
+your home and no vendor cloud sits in the path. The only credential it needs is the Tapo account the
+devices already belong to.
+
+It ships two interfaces over the same core:
+
+- An **MCP server** that assistants such as Claude use as tools (`turn off the office lights`,
+  `is any door open?`).
+- An **HTTP API** with an OpenAPI description at `/docs`, for scripts and dashboards.
+
+## Features
+
+- **One view of the whole house.** Lights, plugs, the H100/H200 hub and its sensors, cameras and the
+  doorbell, each with live state and a clear list of what can be changed.
+- **Safe by default.** Reads are broad; writes are limited to power, brightness and color unless you
+  opt in. Cameras, pairing and hub alarms stay read-only. Wi-Fi names and Matter setup codes are
+  never returned.
+- **Built for real homes.** Discovery combines broadcast with a direct per-address sweep, remembers
+  devices between runs, retries the ones that are slow to wake, and reports honestly when something
+  cannot be reached instead of pretending it is fine.
+- **Fast to answer.** State is cached briefly and device names resolve instantly, so an agent is not
+  blocked on a slow hub.
+- **Tested.** A full suite runs against simulated devices, so it needs no hardware.
+
+## Supported devices
+
+tolpo works with whatever [python-kasa](https://github.com/python-kasa/python-kasa) can talk to, so the list is
+longer than the hardware we own. The table keeps two things apart: what we have run against real devices, and
+what python-kasa documents as supported but we have not tried.
+
+| | Device | Tested here | Documented by python-kasa, not tried here | What an agent gets |
+|---|---|---|---|---|
+| <img src="https://raw.githubusercontent.com/signerless/tolpo/main/assets/devices/light.svg" width="36" alt="Light bulb"> | Color bulbs | L430C | L430P, L530B, L530E, L530EA, L535E | State, brightness, white temperature and color |
+| <img src="https://raw.githubusercontent.com/signerless/tolpo/main/assets/devices/plug.svg" width="36" alt="Smart plug"> | Smart plugs | P115 | P110, P110M | State, plus power, voltage and current readings |
+| <img src="https://raw.githubusercontent.com/signerless/tolpo/main/assets/devices/hub.svg" width="36" alt="Hub"> | Hubs | H200 | H100, and S200B and S200D buttons paired to a hub | The sensors paired to it show up as devices of their own. Its alarm and pairing stay blocked |
+| <img src="https://raw.githubusercontent.com/signerless/tolpo/main/assets/devices/contact.svg" width="36" alt="Door and window sensor"> | Door and window sensors | T110 |  | Open or closed, low-battery flag |
+| <img src="https://raw.githubusercontent.com/signerless/tolpo/main/assets/devices/climate.svg" width="36" alt="Temperature and humidity sensor"> | Temperature and humidity sensors | T310 | T315 (the one with a display) | Temperature, humidity, low-battery flag |
+| <img src="https://raw.githubusercontent.com/signerless/tolpo/main/assets/devices/motion.svg" width="36" alt="Motion sensor"> | Motion sensors |  | T100 | Motion, as python-kasa documents it. Not checked on real hardware |
+| <img src="https://raw.githubusercontent.com/signerless/tolpo/main/assets/devices/leak.svg" width="36" alt="Water leak sensor"> | Water leak sensors | T300 |  | Leak alert and battery level |
+| <img src="https://raw.githubusercontent.com/signerless/tolpo/main/assets/devices/camera.svg" width="36" alt="Camera"> | Cameras | C225, C610, C465 | C100, C101, C110, C200, C210, C220, C325WB, C460, C520WS, C720, TC40, TC65, TC70 | State, battery where there is one, last alert and detection switches. Read-only, no video |
+| <img src="https://raw.githubusercontent.com/signerless/tolpo/main/assets/devices/doorbell.svg" width="36" alt="Video doorbell"> | Doorbells | D230 | D100C, D130 | State and battery. Read-only |
+
+The C610 and the C465 are not on python-kasa's list yet, but both connected fine. The C465 needs the small
+certificate fix in `compat.py`. The full upstream list is in
+[python-kasa's SUPPORTED.md](https://github.com/python-kasa/python-kasa/blob/master/SUPPORTED.md).
+
+A model that is not listed may still work, because tolpo hands the device to python-kasa and shows whatever it
+reports. Run `tolpo scan` to find out. If a device works or does not, tell us through a
+[device support issue](https://github.com/signerless/tolpo/issues/new?template=device_support.yml) so the table can improve.
+
+## Requirements
+
+- Python 3.11 or newer
+- One or more TP-Link Tapo devices on the same network, already set up in the Tapo app
+- Your Tapo account email and password
+- [uv](https://docs.astral.sh/uv/) (or plain `pip`) to install
+
+## Installation
+
+### With npx
+
+You need [Node](https://nodejs.org) and [uv](https://docs.astral.sh/uv/). Nothing is installed globally:
+
+```bash
+npx -y tolpo scan      # find your devices
+npx -y tolpo mcp       # run as an MCP server
+```
+
+tolpo is a Python program. The npm package carries the Python code and runs it with uv, so the first run
+downloads about forty Python packages and takes longer than later runs. If an AI client gives up waiting, run
+`npx -y tolpo --help` once and start the client again.
+
+### From source
+
+```bash
+git clone https://github.com/signerless/tolpo && cd tolpo
+uv venv --python 3.13 .venv
+uv pip install --python .venv/bin/python -e ".[dev]"
+```
+
+## Configuration
+
+Credentials can come from environment variables or a config file. The server reads the file first,
+then lets the environment override it.
+
+```bash
+export TAPO_EMAIL='you@example.com'
+export TAPO_PASSWORD='your-password'
+```
+
+Or `~/.config/tolpo/config.toml` (run `chmod 600` on it, since it holds a password):
+
+```toml
+[tapo]
+email = "you@example.com"
+password = "your-password"
+# or point at an existing JSON file instead of copying the secret:
+# credentials_file = "~/.tapo_config.json"
+
+[server]
+host = "127.0.0.1"          # loopback only; a token is required to bind elsewhere
+port = 8765
+# token = "a-long-random-string"
+# cache_ttl_seconds = 10
+
+[discovery]
+# subnets = ["192.168.1.0/24"]   # default: the /24 of your default-route interface
+# hosts   = ["192.168.10.20"]    # devices that ignore broadcast or live on another VLAN
+# sweep   = true                 # also probe every address in the subnet (networks up to /22)
+interval_seconds = 600
+
+[policy]
+# Features an agent may write beyond power, brightness and color.
+# Plain ids ("pan_left") or kind-qualified ones ("camera.state").
+allow_write = []
+```
+
+Verify your setup with a read-only scan: `npx -y tolpo scan`, or `.venv/bin/tolpo scan` from a source checkout.
+
+## Usage with Claude (MCP)
+
+Put your credentials in `~/.config/tolpo/config.toml` (see Configuration, and `chmod 600` it). The server
+reads that file by itself, so nothing secret ends up in your AI client's settings. Then register the server
+once:
+
+```bash
+claude mcp add tolpo -- npx -y tolpo mcp
+```
+
+From a source checkout, point at your own copy instead:
+
+```bash
+claude mcp add tolpo -- $PWD/.venv/bin/tolpo mcp
+```
+
+If you would rather keep the credentials out of a file, pass them with `-e TAPO_EMAIL=... -e TAPO_PASSWORD=...`,
+but your client will then store them in its own settings in plain text.
+
+After the next restart you can ask things like "dim office-1 to 30%", "is any door open?" or "what is the
+temperature upstairs?".
+
+| Tool | What it does |
+|---|---|
+| `home_overview` | The whole house at a glance: what is on, open doors and windows, water alerts, offline devices, low batteries, temperatures |
+| `list_devices` | Devices with state; filter by `kind` or name |
+| `get_device` | Every feature of one device, and which ones are writable |
+| `set_power` | Switch lights and plugs; accepts several targets and globs like `office*` |
+| `set_light` | Brightness, white temperature, or hue and saturation |
+| `set_feature` | Any other feature, only when the policy allows it |
+| `rescan` | Look for new or moved devices |
+
+Read tools are marked read-only and `set_feature` is marked destructive, so MCP clients can ask for
+confirmation where it matters. Responses are compact: all the devices of a typical home fit in under a
+thousand tokens.
+
+## Usage over HTTP
+
+```bash
+npx -y tolpo serve          # or .venv/bin/tolpo serve from a source checkout
+# http://127.0.0.1:8765, interactive docs at /docs
+```
+
+```bash
+# Read
+curl -s localhost:8765/devices                 # everything, with state and capabilities
+curl -s localhost:8765/devices/front-door       # one device, every feature
+curl -s "localhost:8765/devices?kind=sensor"    # doors, windows, water, temperature
+
+# Write
+curl -s -X POST localhost:8765/devices/desk-lamp/power \
+  -H 'content-type: application/json' -d '{"on": true}'
+curl -s -X POST localhost:8765/devices/office-1/light \
+  -H 'content-type: application/json' -d '{"brightness": 40, "color_temp": 3000}'
+curl -s -X POST localhost:8765/batch/light \
+  -H 'content-type: application/json' -d '{"targets": ["office*"], "brightness": 60}'
+```
+
+A device is addressed by its short `id` (`office-1`), by its name in the Tapo app (case-insensitive),
+or, in the batch endpoints, by a glob such as `office*`. If a name matches several devices the server
+returns `409` with the candidates instead of guessing.
+
+## Security model
+
+This server controls physical things, so it refuses by default and widens only on request.
+
+| Scope | Allowed |
+|---|---|
+| Read | Every feature of every device, except the Wi-Fi name and Matter setup codes, which are never returned |
+| Write by default | Power, brightness, color temperature, color and light presets, on lights and plugs |
+| Write on opt-in | Anything else, named in `policy.allow_write` (alarm test, pan/tilt, detection switches, reboot) |
+| Never | `pair` and `unpair` on the hub |
+
+Cameras are read-only: the `state` switch on a camera is its privacy shutter, not a power relay, so it
+is not treated as one. Enable it deliberately with `allow_write = ["camera.state"]`.
+
+The server listens on `127.0.0.1` only. It refuses to start on any other address without a bearer
+token, and without a token it also rejects requests whose `Host` header is not local, which blocks
+DNS-rebinding attacks from a web page.
+
+Device names are free text typed by whoever set the device up. The server flattens and shortens them
+before an agent sees them, and the instructions it sends tell the agent to treat names and readings as
+data, not commands. A shared Tapo account still means anyone in it can rename a device, so keep the
+account to people you trust.
+
+## How discovery handles a busy network
+
+Homes often have many devices, some battery-powered and slow to answer. Discovery is designed for that:
+
+- A UDP broadcast, followed by a direct query to each address in the subnet (`discovery.sweep`),
+  because some battery cameras ignore broadcasts yet always answer a direct question.
+- Devices seen before are remembered in `~/.cache/tolpo/hosts.json` (address, name and model,
+  no secrets) and queried directly at startup. A device missing from one scan is never forgotten;
+  entries unseen for 30 days are dropped.
+- Devices that do not answer are retried after 5, 15 and 45 seconds, and again on every rescan.
+
+Startup is staged so the server is useful immediately: the first scan runs in the background, and each
+device is connected the moment it answers. A device you name exactly is usable as soon as it is up,
+without waiting for the hub, which can take about ten seconds from cold. Operations that span the whole
+house wait for the scan, but never longer than fifteen seconds; anything still connecting finishes in
+the background.
+
+When something cannot be reached, the answers say so. `home_overview` and `list_devices` carry
+`complete: false` and a `not_connected` list with the name, model and reason for each unreachable
+device, so an agent does not mistake an offline door sensor for a closed door.
+
+## Development
+
+```bash
+.venv/bin/python -m pytest        # runs against simulated devices, no hardware required
+```
+
+Project layout:
+
+```
+src/tolpo/
+  registry.py    device discovery, state cache, control operations
+  policy.py      what may be read and written (deny-by-default)
+  views.py       shared presentation for the HTTP and MCP layers
+  api.py         FastAPI HTTP server
+  mcp_server.py  MCP server (stdio)
+  config.py      config file and environment loading
+  compat.py      small fixes for devices python-kasa cannot reach yet
+  cli.py         serve / mcp / scan entry points
+tests/           full suite against simulated devices
+docs/protocols.md  how Tapo devices talk on the local network
+assets/          logo, device icons and social preview
+```
+
+See [CONTRIBUTING.md](https://github.com/signerless/tolpo/blob/main/CONTRIBUTING.md) for the ground rules, [docs/protocols.md](https://github.com/signerless/tolpo/blob/main/docs/protocols.md) for the protocol notes and
+[SECURITY.md](https://github.com/signerless/tolpo/blob/main/SECURITY.md) to report a vulnerability.
+
+## Background
+
+The protocols behind Tapo devices are not documented by the vendor. Part of this project is independent
+analysis of the official Tapo app and of real devices, done so that software can interoperate with hardware
+its owners already have. The result is written down in [docs/protocols.md](https://github.com/signerless/tolpo/blob/main/docs/protocols.md): which
+transport each model uses, how discovery works, what the newer TPAP protocol looks like, and what we could not
+establish. The notes are in our own words. They contain no vendor code, keys or credentials, and tolpo itself
+only ever signs in with your own Tapo account.
+
+## Compatibility and status
+
+Version 0.1. Lights, plugs, hubs and sensors are fully supported over the KLAP and SSL-AES transports
+through `python-kasa`, plus a small patch (`compat.py`) for cameras with an ECDSA certificate, such as
+the C465, that `python-kasa` cannot reach on its own.
+
+Known limits: cameras and the doorbell are read-only, with no video; the MCP server runs over stdio,
+one process per client, with no shared HTTP transport yet; and devices on a second subnet have not
+been tested.
+
+## License
+
+MIT, see [LICENSE](https://github.com/signerless/tolpo/blob/main/LICENSE).
+
+This project is not affiliated with or endorsed by TP-Link. Tapo is a trademark of TP-Link. All device
+communication goes through the open source
+[python-kasa](https://github.com/python-kasa/python-kasa) library.
+
+<!-- mcp-name: io.github.signerless/tolpo -->

package/bin/tolpo.js

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+"use strict";
+
+// tolpo is a Python program. This launcher exists so that `npx tolpo mcp` works: it runs the Python code
+// shipped inside this package with uvx, which builds an isolated environment the first time.
+//
+// The launcher must never write to stdout. With `tolpo mcp`, stdout carries the MCP protocol, and
+// stdin, stdout and stderr are handed to the child process untouched.
+
+const { spawn } = require("node:child_process");
+const { constants } = require("node:os");
+const path = require("node:path");
+
+const root = path.resolve(__dirname, "..");
+
+const MISSING_UV = `tolpo runs its Python code through uv, and uvx was not found on your PATH.
+
+Install uv, then run this again:
+  macOS and Linux:  curl -LsSf https://astral.sh/uv/install.sh | sh
+  Homebrew:         brew install uv
+  Windows:          powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
+
+More options: https://docs.astral.sh/uv/getting-started/installation/
+If an editor or an AI client starts tolpo, make sure it can see uv: use the full path to uvx or add its
+folder to the PATH that the client uses.
+`;
+
+const child = spawn("uvx", ["--from", root, "tolpo", ...process.argv.slice(2)], { stdio: "inherit" });
+
+child.on("error", (error) => {
+  if (error.code === "ENOENT") {
+    process.stderr.write(MISSING_UV);
+    process.exit(127);
+  }
+  process.stderr.write(`tolpo could not start uvx: ${error.message}\n`);
+  process.exit(1);
+});
+
+child.on("exit", (code, signal) => {
+  if (signal) {
+    process.exit(128 + (constants.signals[signal] || 0));
+  }
+  process.exit(code === null ? 1 : code);
+});
+
+for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"]) {
+  process.on(signal, () => child.kill(signal));
+}

package/package.json

@@ -1,6 +1,42 @@
 {
   "name": "tolpo",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Local-first MCP server and HTTP API that let AI agents read and control TP-Link Tapo smart-home devices",
+  "license": "MIT",
+  "author": "signerless",
+  "homepage": "https://github.com/signerless/tolpo#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/signerless/tolpo.git"
+  },
+  "bugs": {
+    "url": "https://github.com/signerless/tolpo/issues"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "tapo",
+    "tp-link",
+    "smart-home",
+    "home-automation",
+    "ai-agents",
+    "local-first"
+  ],
+  "mcpName": "io.github.signerless/tolpo",
+  "bin": {
+    "tolpo": "bin/tolpo.js"
+  },
+  "files": [
+    "bin/",
+    "src/tolpo/*.py",
+    "pyproject.toml",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test"
+  }
+}

package/pyproject.toml

@@ -0,0 +1,64 @@
+[project]
+name = "tolpo"
+dynamic = ["version"]
+description = "Local-first MCP server and HTTP API that let AI agents read and control TP-Link Tapo smart-home devices"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "signerless" }]
+keywords = [
+    "mcp",
+    "model-context-protocol",
+    "tapo",
+    "tp-link",
+    "smart-home",
+    "home-automation",
+    "ai-agents",
+    "local-first",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: End Users/Desktop",
+    "Topic :: Home Automation",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Framework :: AsyncIO",
+    "Framework :: FastAPI",
+]
+requires-python = ">=3.11"
+dependencies = [
+    "python-kasa>=0.11",
+    "fastapi>=0.115",
+    "uvicorn>=0.30",
+    "mcp>=2.3",
+]
+
+[project.urls]
+Homepage = "https://github.com/signerless/tolpo"
+Documentation = "https://github.com/signerless/tolpo#readme"
+Repository = "https://github.com/signerless/tolpo"
+Issues = "https://github.com/signerless/tolpo/issues"
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "httpx>=0.27"]
+
+[project.scripts]
+tolpo = "tolpo.cli:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.version]
+path = "src/tolpo/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/tolpo"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

package/src/tolpo/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

package/src/tolpo/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+main()

package/src/tolpo/api.py

@@ -0,0 +1,154 @@
+"""HTTP surface. Small on purpose: list, inspect, switch, dim, and a guarded generic setter."""
+
+from __future__ import annotations
+
+import secrets
+from contextlib import asynccontextmanager
+
+from fastapi import Depends, FastAPI, Header, HTTPException
+from fastapi.responses import JSONResponse
+from pydantic import BaseModel, Field, JsonValue
+from starlette.middleware.trustedhost import TrustedHostMiddleware
+
+from . import __version__
+from .config import Config
+from .registry import Registry, RegistryError
+from .views import BatchItem, DeviceDetail, DeviceSummary, detail, run_batch, summary
+
+DESCRIPTION = """
+Local control of smart-home devices for AI agents.
+
+Refer to a device by its short `id` (`office-1`), by its name as shown in the app
+(case-insensitive), or by a glob (`office*`) in the batch endpoints.
+
+Reads are broad; writes are limited to power, brightness and color unless the owner
+widens `policy.allow_write`. Responses never include Matter setup codes or the Wi-Fi name.
+"""
+
+
+class PowerBody(BaseModel):
+    on: bool
+
+
+class LightBody(BaseModel):
+    on: bool | None = Field(None, description="Also switch the light on (true) or off (false)")
+    brightness: int | None = Field(None, ge=1, le=100)
+    color_temp: int | None = Field(None, ge=1000, le=12000, description="Kelvin; white light")
+    hue: int | None = Field(None, ge=0, le=360)
+    saturation: int | None = Field(None, ge=0, le=100)
+
+
+class FeatureBody(BaseModel):
+    value: JsonValue = None
+
+
+class BatchPower(PowerBody):
+    targets: list[str] = Field(min_length=1, examples=[["office*", "Desk Lamp"]])
+
+
+class BatchLight(LightBody):
+    targets: list[str] = Field(min_length=1, examples=[["office*"]])
+
+
+def create_app(
+    cfg: Config,
+    registry: Registry | None = None,
+    *,
+    discover: bool = True,
+    allowed_hosts: list[str] | None = None,
+) -> FastAPI:
+    reg = registry or Registry(cfg)
+
+    @asynccontextmanager
+    async def lifespan(_: FastAPI):
+        await reg.start(discover=discover)
+        yield
+        await reg.stop()
+
+    app = FastAPI(title="tolpo", version=__version__, description=DESCRIPTION, lifespan=lifespan)
+
+    if not cfg.token:
+        # Without a token the only protection is the loopback bind, so also refuse requests
+        # whose Host header is not local (blocks DNS-rebinding from a web page).
+        app.add_middleware(TrustedHostMiddleware, allowed_hosts=allowed_hosts or ["localhost", "127.0.0.1"])
+
+    async def require_token(authorization: str | None = Header(default=None)) -> None:
+        if not cfg.token:
+            return
+        scheme, _, supplied = (authorization or "").partition(" ")
+        if scheme.lower() != "bearer" or not secrets.compare_digest(supplied.encode(), cfg.token.encode()):
+            raise HTTPException(401, "missing or invalid bearer token", headers={"WWW-Authenticate": "Bearer"})
+
+    auth = [Depends(require_token)]
+
+    @app.exception_handler(RegistryError)
+    async def on_registry_error(_, exc: RegistryError):
+        return JSONResponse(status_code=exc.status_code, content={"error": str(exc), "candidates": exc.candidates})
+
+    @app.get("/health")
+    async def health():
+        return {"status": "ok", "version": __version__}
+
+    @app.get("/status", dependencies=auth, summary="Discovery status and devices that are offline")
+    async def status():
+        return reg.health()
+
+    @app.post("/scan", dependencies=auth, summary="Search the network for new or moved devices")
+    async def scan():
+        await reg.discover()
+        return reg.health()
+
+    @app.get("/devices", response_model=list[DeviceSummary], dependencies=auth, summary="List devices")
+    async def list_devices(kind: str | None = None, q: str | None = None, fresh: bool = False):
+        """Filter by `kind` (light, plug, sensor, camera...) or by text in the name with `q`.
+        State is cached for a few seconds; pass `fresh=true` to ask the devices again."""
+        items = reg.entries(kind=kind, q=q)
+        await reg.refresh_all(items, force=fresh)
+        return [summary(reg, e) for e in items]
+
+    @app.get("/devices/{ref}", response_model=DeviceDetail, dependencies=auth, summary="Full detail of one device")
+    async def get_device(ref: str):
+        entry = reg.resolve_one(ref)
+        await reg.refresh(entry)
+        return detail(reg, entry)
+
+    @app.post("/devices/{ref}/power", response_model=DeviceSummary, dependencies=auth, summary="Switch on or off")
+    async def power(ref: str, body: PowerBody):
+        entry = reg.resolve_one(ref)
+        await reg.set_power(entry, body.on)
+        return summary(reg, entry)
+
+    @app.post("/devices/{ref}/toggle", response_model=DeviceSummary, dependencies=auth, summary="Flip the power state")
+    async def toggle(ref: str):
+        entry = reg.resolve_one(ref)
+        await reg.toggle(entry)
+        return summary(reg, entry)
+
+    @app.post("/devices/{ref}/light", response_model=DeviceSummary, dependencies=auth, summary="Brightness and color")
+    async def light(ref: str, body: LightBody):
+        entry = reg.resolve_one(ref)
+        await reg.set_light(entry, **body.model_dump())
+        return summary(reg, entry)
+
+    @app.put(
+        "/devices/{ref}/features/{feature_id}",
+        response_model=DeviceSummary,
+        dependencies=auth,
+        summary="Set any feature the policy allows",
+    )
+    async def put_feature(ref: str, feature_id: str, body: FeatureBody):
+        entry = reg.resolve_one(ref)
+        await reg.set_feature(entry, feature_id, body.value)
+        return summary(reg, entry)
+
+    @app.post("/batch/power", response_model=list[BatchItem], dependencies=auth, summary="Switch several devices")
+    async def batch_power(body: BatchPower):
+        return await run_batch(reg, body.targets, lambda e: reg.set_power(e, body.on))
+
+    @app.post("/batch/light", response_model=list[BatchItem], dependencies=auth, summary="Set several lights")
+    async def batch_light(body: BatchLight):
+        settings = body.model_dump(exclude={"targets"})
+        return await run_batch(reg, body.targets, lambda e: reg.set_light(e, **settings))
+
+    return app
+