Ordres et sceaux
Un ordre, ce sont des octets : ceux que vous lisez, ceux que vous signez, ceux que l'agent vérifie. Rien d'autre n'est jamais interprété.
Ce qui est signé
La console demande au central de préparer l'ordre à partir de la déclaration de l'action. Le central fixe les octets, en JSON compact :
{
"v": 1,
"id": "0f6c…",
"agent": "a1b2c3d4e5f60718",
"project": "cas-market",
"env": "production",
"action": "payments.retry",
"params": { "reference": "PAY-1042" },
"issued_at": 1794300000,
"expires_at": 1794300300,
"nonce": "<base64url, ≥ 16 octets>"
}id: unique, 16 à 64 caractères[A-Za-z0-9_-].agent: l'empreinte de l'agent destinataire.expires_at: au plus 300 secondes aprèsissued_at.- Un champ inconnu fait refuser l'ordre.
Le défi WebAuthn
défi = SHA-256( "kantama/ordre/v1" ‖ 0x00 ‖ octets_de_l_ordre )
Le préfixe sépare les usages : une signature d'ordre ne peut servir à rien d'autre, ni à une connexion ni à un autre geste.
Avant de signer, la console (et l'app mobile) décode ces octets-là pour l'écran de confiance et recalcule le défi. S'il diffère de celui que propose le central, elle refuse de signer.
Préparer, relire, signer
- Préparer : le central vérifie que l'action est dans la liste fermée et permise dans cet environnement, valide les paramètres comme l'agent (motif ancré, bornes, longueur, choix, caractères de contrôle et paramètres inconnus refusés), puis crée un brouillon.
- Relire : l'écran de confiance montre ce qui est dans les octets, jamais un résumé du central.
- Signer : chaque appareil ajoute son approbation. Le central refuse une passkey déjà comptée ou d'un autre espace.
- Transmettre : au niveau atteint (1 passkey, ou 2 distinctes pour
double), l'ordre part vers l'agent.
Le sceau et le nombre
Deux repères permettent de vérifier d'un coup d'œil que l'ordinateur et le téléphone montrent le même ordre :
- le sceau : un motif de 16 cases, les 16 premiers bits de
SHA-256(id); - le nombre de l'ordre :
10 + SHA-256("kantama/nombre/v1:" ‖ id)[0] mod 90. Le téléphone propose trois nombres, le bon et deux leurres écartés d'au moins 3, sans en présélectionner aucun.
Le nombre est demandé en production, et dès qu'un autre appareil a déjà signé. Les mêmes valeurs sont recalculées par le central, la console et l'app mobile, contre des vecteurs partagés :
# exemple d'ordre
id ord_0f6c1d2e8b7a45e1
sceau 1000011010001111
nombre 69
choix 24 · 30 · 69Ce que vérifie l'agent
- Décodage de l'enveloppe et de l'ordre, en JSON strict.
v = 1, etagent= sa propre empreinte.- Les dates : émis au plus 30 s dans le futur, pas expiré, durée de 300 s au plus, émis après son propre démarrage. Ainsi l'anti-rejeu survit à un redémarrage sans rien écrire sur le disque.
projectetenvconnus,actiondans la liste fermée.- Les paramètres, contre la déclaration de l'action. Un paramètre inconnu est refusé.
- Chaque signature : passkey de sa liste de confiance, type
webauthn.get, bon défi, origine autorisée, présence et vérification de l'utilisateur, signature ES256 ou RS256. - Le niveau : une passkey valide pour
single, deux passkeys distinctes pourdouble. - L'anti-rejeu : l'identifiant est retenu jusqu'à son expiration ; un second passage est refusé.
Niveaux des actions du socle
| Action | Niveau |
|---|---|
core.trust.add — ajouter une passkey de confiance | deux passkeys |
core.trust.remove — retirer une passkey (jamais la dernière) ; de même core.member.remove et core.rp.remove | deux passkeys qui restent dans la liste (une seule s'il n'en reste qu'une capable de gouverner l'agent), jamais celle qu'on retire |
core.service.restart — redémarrer un service | une passkey |
core.deploy, core.rollback — déployer un commit, revenir à la version précédente | une passkey |
core.preview.deploy, core.preview.remove — prévisualisations par branche | une passkey |
core.secrets.apply — appliquer un lot de variables | deux passkeys si l'environnement commence par prod, une ailleurs |
core.backup.run, core.backup.test — sauvegarder, restaurer à l'essai | une passkey |
core.project.pause, core.project.resume | une passkey |
core.project.remove — détacher le projet (rien n'est effacé) | deux appareils |
core.vercel.redeploy, core.vercel.promote, core.github.rerun, core.github.dispatch | deux appareils en production |
core.cloudflare.purge | une passkey |
Les actions de votre kantama.yaml déclarent leur propre niveau (level: single ou double).
Le reçu de l'agent
Pour chaque ordre, l'agent signe un reçu avec sa clé Ed25519 (domaine kantama/recu/v1). Le central vérifie cette signature avant de l'inscrire au journal.
{
"v": 1,
"order_id": "0f6c…",
"order_sha256": "<SHA-256 des octets exacts de l'ordre>",
"agent": "c41e9a075d2f7be0",
"status": "refused",
"reason": "ordre expiré",
"at": 1794300012
}accepted : vérifié, l'agent l'exécute ensuite. refused : une vérification a échoué, ou la même action est déjà en cours dans cet environnement. Après l'exécution, l'agent signe un résultat (domaine kantama/resultat/v1) : statut, code de sortie, durée et dernières lignes.
Les propositions de modification de la documentation ne sont pas encore ouvertes au public.