Jetons de décision

Lorsqu'un point de contrôle arrive à une décision finale, Maetra émet une jeton de décision — un JWT signé en decision_tokenC'est vrai. Elle lie la décision à l'enveloppe d'action canonique, aux versions exactes des politiques, à l'espace de travail et à l'exécuteur-exécuteur prévu.

Vérifiez-le localement pour le rejet rapide, puis consommez-le par POST /v1/executions/authorize immédiatement avant l'action extérieure. Ce contrôle faisant autorité impose la révocation et la sémantique à usage unique.

Clés publiques (JWKS)#

GET /.well-known/jwks.json — Aucune authentification n'est requise. Renvoie l'ensemble de clés utilisé pour signer les jetons de décision. Récupère une fois et cache; l'en-tête du jeton kid identifie la clé qui l'a signée.

curl "https://api.maetra.io/.well-known/jwks.json" \
  -H "Authorization: Bearer $MAETRA_API_KEY"

{ "keys": [ { "kty": "OKP", "crv": "Ed25519", "alg": "EdDSA", "kid": "…", "x": "…" } ] }

Vérification d'un jeton#

Les jetons de décision sont signés avec EdDSA utilisant Ed25519C'est vrai. Vérifier avec une bibliothèque JWT qui prend en charge Ed25519 et le JWKS ci-dessus.

import { jwtVerify, createRemoteJWKSet } from "jose";


const JWKS = createRemoteJWKSet(new URL("https://api.maetra.io/.well-known/jwks.json"));


export async function verifyDecision(token: string) {
  const { payload } = await jwtVerify(token, JWKS, {
    algorithms: ["EdDSA"],
    issuer: "maetra-govern",
    audience: "payments-worker",
  });
  if (payload.status !== "approved" || payload.maxUses !== 1) {
    throw new Error(`Action not approved: ${payload.status}`);
  }
  return payload; // identifies the checkpoint, action, decision, and expiry
}

Quoi vérifier

Signature — doit être validée par une clé dans le JWKS.
status — ne procéder que lorsque: approuvé.
Expiration — refus des jetons expirés (standard exp).
Émetteur et public — exiger iss=maetra-govern et votre exécuteur est exact. aud valeur.
Reliure — recalculer et comparer actionEnvelopeHash, puis comparer checkpointId, workspaceIdet policyDigest.
Utiliser le plafond — exiger maxUses=1 et d'autoriser par l'intermédiaire d'Maetra ainsi un replay ou jeton révoqué échoue à l'exécution.

Remarque Traiter le jeton comme une capacité d'utilisation unique de courte durée. decision_token_expires_at limite le jeton; point de contrôle expires_at est le délai d'approbation.