Tokens de decisión

Cuando un punto de control llega a una decisión terminal, Maetra emite un decisión token - un JWT firmado en decision_token. Se une la decisión al sobre de acción canónica, las versiones exactas de política, el espacio de trabajo y el ejecutante previsto.

Verificarlo localmente para el rechazo rápido, luego consumirlo a través de POST /v1/executions/authorize inmediatamente antes de la acción externa. Ese cheque autorizado impone la revocación y la semántica de un uso.

Llaves públicas (JWKS)#

GET /.well-known/jwks.json — No se requiere autenticación. Devuelve el conjunto clave utilizado para firmar tokens de decisión. Coge una vez y cache; la cabecera de token kid Identifica qué clave lo firmó.

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

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

Verificando una ficha#

Las fichas de decisión se firman con EdDSA usando Ed25519. Verifica con una biblioteca JWT que soporta Ed25519 y el JWKS arriba.

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
}

Qué hacer para comprobar

• Firma - debe validar contra una llave en el JWKS.
• status - Proceder sólo cuando aprobado.
• Gastos - rechazar fichas caducadas (estándar) exp).
• Periodista y público - Requerimientos iss=maetra-govern y su ejecutor es exacto aud valor.
• Binding — recomputar y comparar actionEnvelopeHash, entonces compare checkpointId, workspaceId, y policyDigest.
• Uso del techo - Requerimientos maxUses=1 y autorizar a través de Maetra para que una ficha repetida o revocada falla en la ejecución.

Nota Tratar el token como una capacidad de vida corta y de un uso. decision_token_expires_at atado el token; punto de control expires_at es el tiempo de aprobación.