routes
diapason.mesh.routes
¶
REST API for the device mesh.
Everything here is authenticated by the local API key EXCEPT one route:
POST /v1/mesh/pairings/redeem. A device being enrolled does not have the
key yet — that is the whole point of enrolment — so it authenticates with
the one-time pairing token instead, exactly as Succès sync already does.
That route is rate-limited on its own bucket (see _OPEN_MESH_ROUTES in
the auth middleware), because it is the mesh's front door. It was not, for a
while: the limiter ran only for paths that require the API key, so opening a
route to unauthenticated devices silently opened it to unlimited traffic too.
ack_commands(body)
¶
A device reporting what it did with what it collected.
Without this half a polled command would stay PENDING forever and the user would never learn whether it happened — which is the same failure as claiming it did.
announce(appState='')
¶
Push our own presence to every peer we know how to reach.
Behind the key wall: this is the local app asking to be seen, not a stranger asking to be believed.
command_history(limit=50)
¶
Recent commands, newest first (spec §43).
declare_capabilities(device_id, body)
¶
Record what a device claims. The grant is computed, never taken.
deliver_command(body)
¶
Receive a command from another device.
Outside the API-key wall on purpose, and NOT unauthenticated: the envelope's Ed25519 signature is the credential, checked against the key recorded when the sender was paired. A stronger proof than a shared secret, since it also binds the exact arguments.
forget_device(device_id)
¶
Erase a device outright — the only way back from revocation.
inbox(drain=True)
¶
What the local shell should open or show, oldest first.
Polled by the desktop app; draining on read means a screen is opened once, not on every poll.
list_tools()
¶
The remote catalogue, as the assistant's router should advertise it.
poll_commands(body)
¶
A device asking for whatever is waiting for it.
Outside the API-key wall, like the other two device-signed surfaces. This is how a phone joins the mesh at all: it has no address to be dialled at, so it comes to fetch. The poll doubles as its heartbeat — asking for your commands proves you are awake better than any beacon.
receive_presence(body)
¶
A paired device announcing itself.
Outside the API-key wall for the same reason as /commands/deliver:
a device that joined this fleet never receives this machine's key, and
its Ed25519 signature is a stronger credential anyway — it binds the
exact claim, including the address commands will later be sent to.
redeem_pairing(body)
¶
Enrol a device that presents a valid invitation.
Deliberately outside the API-key wall: the joining device has no key. The invitation is the credential, and it is single-use and short-lived.
send_command(body)
¶
Send a command to another device. Authenticated by the local API key: this is the assistant or the UI on THIS machine asking.
whoami()
¶
This installation's own identity — public half only.