Skip to content

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.