commands
diapason.mesh.commands
¶
The signed command envelope, and the eleven checks it must survive.
A command crossing between devices is the mesh's sharpest edge: it makes one machine act on another's word. Spec §9 lists what must be verified, and the value of the list is that it is verified in ONE place — a check spread across call sites is a check that will be forgotten at one of them.
identity · origin · destination · signature · expiry · nonce ·
idempotency · permissions · capabilities · risk · confirmation
Two properties are worth stating plainly, because they are what make the difference between a protocol and a hope:
- The signature covers the whole envelope EXCEPT itself, over canonical bytes. Change one character of one argument and verification fails.
- A nonce may be spent once. Replaying a captured command — the classic way to make "open this" become "open this forty times" — is refused by the second attempt, even with a perfect signature.
CommandError
¶
Bases: RuntimeError
Malformed command — the sender got the protocol wrong.
CommandRejected
¶
Bases: RuntimeError
A well-formed command that must not run.
Carries a machine-readable code for the caller's status field and a
French message safe to show the user (never the failing signature,
never a nonce, never an argument value).
NonceStore
¶
Spent nonces, so a captured command cannot be replayed.
Entries are pruned past the maximum command lifetime: a nonce can only be replayed while its command could still be valid, so remembering it beyond that adds storage without adding safety.
spend(nonce, device_id, *, retention_ms=3600000)
¶
Consume nonce. False when it was already spent — a replay.
The INSERT itself is the check: relying on the primary key makes the test atomic, where a SELECT-then-INSERT would let two concurrent deliveries of the same command both pass.
RemoteCommand
dataclass
¶
One instruction from one device to another (spec §8).
est_scelle
property
¶
Le contenu de cette commande voyage-t-il chiffré ?
to_dict(*, with_signature=True)
¶
L'enveloppe telle qu'elle part sur le fil.
INVARIANT DU SCELLEMENT, et tout en dépend : .tool,
.arguments et .requires_confirmation portent TOUJOURS le
clair, des deux côtés du réseau. _extra["scelle"] porte le
triplet chiffré exactement tel qu'il a été signé, et c'est LUI que
cette méthode réémet.
Sans cette règle, le récepteur rangerait dans sa file une enveloppe portant le clair sous une signature calculée sur le chiffré — donc une enveloppe qui ne vérifierait plus sa propre signature. C'est le bogue que la première version du plan s'annonçait comme bénéfice avant de l'introduire.
Une commande CLAIRE (_extra vide) produit exactement les mêmes
octets qu'avant le 26 août 2026. C'est ce qui protège le client
mobile figé, et un test le compare à un vecteur gelé plutôt que de
s'en remettre à la lecture.
build_command(*, owner_id, origin_device_id, target_device_id, tool, arguments=None, ttl_ms=DEFAULT_TTL_MS, requires_confirmation=False, confirmation_id='', idempotency_key='')
¶
Assemble an unsigned command with fresh anti-replay material.
sign_command(command)
¶
Sign with THIS device's private key, over everything but the signature.
verify_command(raw, *, registry, local_device_id, local_owner_id, nonces, now=None)
¶
Run every check of spec §9. Raises on the first failure.
Order matters: the cheap structural checks come first so a malformed or misaddressed command never reaches the cryptography, and the nonce is spent LAST — otherwise a command rejected for another reason would burn a nonce the legitimate sender still needs.