Nouveau · l'app mobile, second appareil pour relire et signer chaque ordre
kantamaSe connecterCréer un espace

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é.

3 minutesMis à jour le 18 novembre 2026

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 :

ordre · v1
{
  "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ès issued_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

  1. 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.
  2. Relire : l'écran de confiance montre ce qui est dans les octets, jamais un résumé du central.
  3. Signer : chaque appareil ajoute son approbation. Le central refuse une passkey déjà comptée ou d'un autre espace.
  4. 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 · 69

Ce que vérifie l'agent

  1. Décodage de l'enveloppe et de l'ordre, en JSON strict.
  2. v = 1, et agent = sa propre empreinte.
  3. 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.
  4. project et env connus, action dans la liste fermée.
  5. Les paramètres, contre la déclaration de l'action. Un paramètre inconnu est refusé.
  6. 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.
  7. Le niveau : une passkey valide pour single, deux passkeys distinctes pour double.
  8. L'anti-rejeu : l'identifiant est retenu jusqu'à son expiration ; un second passage est refusé.

Niveaux des actions du socle

ActionNiveau
core.trust.add — ajouter une passkey de confiancedeux passkeys
core.trust.remove — retirer une passkey (jamais la dernière) ; de même core.member.remove et core.rp.removedeux 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 serviceune passkey
core.deploy, core.rollback — déployer un commit, revenir à la version précédenteune passkey
core.preview.deploy, core.preview.remove — prévisualisations par brancheune passkey
core.secrets.apply — appliquer un lot de variablesdeux passkeys si l'environnement commence par prod, une ailleurs
core.backup.run, core.backup.test — sauvegarder, restaurer à l'essaiune passkey
core.project.pause, core.project.resumeune 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.dispatchdeux appareils en production
core.cloudflare.purgeune 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.

reçu · v1
{
  "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.

Cette page vous a-t-elle aidé ?Modifier cette page

Les propositions de modification de la documentation ne sont pas encore ouvertes au public.