Rédemption à usage unique

Une capacité est un billet d’autorisation à usage unique. La rédemption le consomme juste avant l’effet, après avoir revérifié que l’autorité qui le fonde tient toujours. Elle décide de l’autorité, jamais de l’effet.

État : Expérimental · V1 en construction. Aucune revue ni aucun audit indépendants. Rédigé d’après le commit 397ba8c d’authority-graph ; le code source reste la référence.

Le cycle : émettre, racheter, exécuter

  1. Émettre. issue() reçoit le demandeur authentifié, une clé d’idempotence du client, une commande nommant un action_id et un enforcement_point_id, et un authorityTime explicite. Si les validateurs du moteur acceptent, elle enregistre un événement CAPABILITY_ISSUED : la capacité, l’action et son empreinte, la séquence de décision, la chaîne accordée, le point d’application et l’expiration. Elle peut refuser, par exemple avec REQUESTER_MISMATCH, STALE_AUTHORITY_TIME ou CAPACITY_EXCEEDED.
  2. Racheter. Juste avant l’effet, le point d’application appelle redeem() avec le principal authentifié, une commande et un authorityTime explicite. La commande porte l’identifiant de la capacité, celui du point d’application, ainsi que la capacité et les paramètres qu’il s’apprête à exécuter.
  3. Exécuter. Seulement si redeem() renvoie ok: true, l’appelant peut exécuter l’effet, une seule fois. Authority n’exécute jamais l’action : c’est le système de l’appelant qui le fait.

Ce que la rédemption revérifie

  • Le billet existe et reste une attribution cohérente du journal (CAPABILITY_NOT_FOUND, CAPABILITY_NOT_VALID).
  • Le demandeur authentifié est celui enregistré sur la demande d’action, jamais une valeur prise dans la commande (REQUESTER_MISMATCH).
  • Le point d’application est celui du billet (WRONG_ENFORCEMENT_POINT).
  • Le billet n’a pas été racheté (ALREADY_REDEEMED) et n’a pas expiré : un authorityTime strictement antérieur à expires_at est valide, sinon EXPIRED.
  • Ce que le point d’application s’apprête à exécuter a la même empreinte que le billet (ARGUMENTS_MISMATCH). Les arguments d’outil ne sont liés que si les paramètres de l’action portent un arguments_digest (schéma d’empreinte V2) ; avec le schéma V1, seuls la capacité, le montant, la devise et le destinataire sont liés.
  • La délégation est résolue de nouveau sur tout le journal à l’instant propre de la commande. Si elle n’est plus autorisée (révoquée, expirée, un maillon perdu), le résultat est AUTHORITY_NO_LONGER_VALID.
  • authorityTime n’est pas plus ancien qu’un instant déjà présent dans le journal (STALE_AUTHORITY_TIME).

L’ordre des refus est fixe : introuvable, non valide, demandeur, instant périmé, point d’application, déjà racheté, expiré, arguments, autorité.

Une seule rédemption réussie

Il existe au plus un événement CAPABILITY_REDEEMED par capacité. Le noyau de décision refuse le second (ALREADY_REDEEMED), et l’ingestion le refuse indépendamment comme collision d’identifiant métier. En mémoire, les rédemptions sur un même magasin sont sérialisées par un verrou propre à ce magasin.

Sur PostgreSQL, une transaction SQL prend le verrou consultatif d’écriture partagé avec tous les autres écrivains de authority_events, relit tout le journal, décide, insère et relit avant de valider. Un index unique partiel, authority_events_redeemed_capability_id_uidx, rend impossible une seconde ligne de rédemption, même pour un écrivain qui ignore le verrou. REDEEMED n’est renvoyé que si cette transaction a elle-même inséré la ligne et que la relecture montre exactement une ligne de rédemption pour la capacité ; une violation d’unicité est rapportée comme REDEMPTION_COLLISION. Cela est testé avec des connexions concurrentes et avec des processus distincts du système d’exploitation, dont un processus tenant le verrou qui est tué.

La rédemption ne modifie aucune décision antérieure et ne libère aucune capacité : une capacité rachetée reste engagée.

Ce que cela ne garantit pas

Ce qui est borné, c’est l’autorisation : au plus une rédemption réussie par billet. Rien ici ne garantit qu’un effet externe a lieu, a lieu une seule fois, ou est annulé. REDEEMED autorise l’effet ; seul le système cible peut le dédupliquer ou le vérifier. Un effet légitime peut même être perdu, par exemple après un résultat inconnu, car Authority ne produit jamais un second ok: true.

Résultats

Ce que chaque résultat signifie pour le billet et pour le journal
RésultatÉvénement écritBillet consomméL’effet peut s’exécuterL’appelant doit
REDEEMEDoui, juste après la décisionouiouiexécuter l’effet, une fois
CAPABILITY_NOT_FOUND, CAPABILITY_NOT_VALID, REQUESTER_MISMATCH, WRONG_ENFORCEMENT_POINT, EXPIRED, ARGUMENTS_MISMATCH, AUTHORITY_NO_LONGER_VALID, STALE_AUTHORITY_TIMEnonnonnoncorriger la cause, ou autoriser de nouveau
ALREADY_REDEEMED, REDEMPTION_COLLISIONnon, pas par cet appeloui, par un autre appelnonne pas réessayer : cet appel n’a jamais autorisé l’effet
CONCURRENT_WRITE_DETECTED, en mémoireoui, mais pas juste après la décisionouinonautoriser de nouveau ; cela peut se heurter à CAPACITY_EXCEEDED
CONCURRENT_WRITE_DETECTED, sur PostgreSQLnon, annulénonnonréessayer : la décision est reprise sur le nouveau journal
RedemptionSchemaError, sur PostgreSQLnon, levée avant toute écriturenonnoncorriger la migration, puis réessayer le même billet
toute autre exception, sur PostgreSQLinconnuinconnunonréessayer le même billet quand la base est de nouveau joignable

Résultats inconnus sur PostgreSQL

Sur PostgreSQL, trois situations doivent rester distinctes. Elles ne sont pas équivalentes.

  • Un refus métier. redeem() renvoie ok: false avec une raison. C’est un résultat connu, pas une exception : le tableau des résultats dit si le billet est consommé, et l’effet ne doit pas s’exécuter.
  • Une erreur de configuration connue. RedemptionSchemaError est levée avant toute écriture, parce que l’index de rédemption est absent, invalide, non unique ou mal défini. Ce n’est pas un résultat inconnu. L’effet ne doit pas s’exécuter ; corrigez la migration, puis réessayez le même billet (l’échec n’est pas mis en cache).
  • Toute autre exception, par exemple une connexion perdue ou une erreur du serveur. De l’extérieur, on ne peut pas savoir si elle est survenue avant la validation, autour d’elle, ou après une validation dont l’accusé a été perdu. La plupart de ces échecs ne laissent rien d’écrit, mais l’appel ne peut pas le dire : considérez le résultat comme inconnu.

Sur une exception, l’effet ne doit jamais s’exécuter sur cet appel : cela reste fail-closed, quelle que soit l’exception. Seul le troisième cas demande le protocole de reprise, et seulement quand la base est de nouveau joignable :

  1. Réessayer le même billet.
  2. REDEEMED signifie que la première tentative n’avait pas été validée : exécuter l’effet une fois.
  3. ALREADY_REDEEMED signifie que le billet est consommé, par la tentative perdue ou par un autre appelant, et Authority ne peut pas distinguer lequel : ne pas exécuter l’effet, et autoriser de nouveau avec une nouvelle capacité.

Un jeton de récupération par tentative, qui permettrait de distinguer les deux cas, n’est pas fourni. En mémoire, une écriture concurrente consomme le billet sans rien autoriser, et la capacité qu’il engageait reste engagée : autoriser de nouveau la même action face à un budget total peut alors être refusé avec CAPACITY_EXCEEDED. Ce coût en disponibilité a été accepté pour la V1 ; la sûreté n’est pas affectée.

Mise en place de PostgreSQL

schema.sql est la migration et est idempotent. La construction de l’index unique bloque les écritures pendant qu’elle s’exécute ; sur un gros journal, construisez-le d’abord à la main avec CREATE UNIQUE INDEX CONCURRENTLY. Une construction concurrente qui échoue laisse un index invalide qui ne garantit rien. Chaque PostgresCapabilityRedemptionTransaction vérifie donc l’index avant sa première rédemption et lève RedemptionSchemaError, sans rien écrire, s’il n’est pas en vigueur.

Le pool que vous fournissez doit avoir un écouteur d’erreur, pool.on("error", ...), pour les clients inactifs dont la connexion est perdue. La transaction protège le client qu’elle a emprunté, pas le pool : sans votre écouteur, une erreur sur un client inactif n’est pas gérée par Authority.

Exemples conformes au code actuel

Ce sont des extraits pédagogiques, pas une bibliothèque ni un SDK (le SDK est prévu et non commencé). Les variables et fonctions qu’ils utilisent sont fournies par votre application. runEffectOnce est une fonction illustrative : Authority ne l’exécute pas, et ne garantit pas qu’un effet externe s’exécute une seule fois. Seul le système cible peut le faire. Ces exemples ne sont pas non plus une configuration complète de production : ils omettent les identifiants et TLS, le rôle de base de données applicatif, la taille du pool et les délais, les nouvelles tentatives avec attente, la journalisation et la supervision.

En mémoire. store est un InMemoryEventStore qui contient déjà le billet émis, et command est une RedeemCapabilityCommand avec capability_id, enforcement_point_id, observed_capability et observed_parameters. runEffectOnce et refuseEffect représentent votre propre code.

import { InMemoryCapabilityRedemptionTransaction } from "./src/storage/capabilityRedemptionTransaction.js";
import { iso8601, principalId } from "./src/domain/types.js";

const redemption = new InMemoryCapabilityRedemptionTransaction(store);
const result = await redemption.redeem(
  { principalId: principalId("agent-a") },
  command,
  iso8601("2024-01-01T00:05:00.000Z"),
);
if (result.ok) {
  runEffectOnce(result.redemption);
} else {
  refuseEffect(result.reason);
}

PostgreSQL, où pool est un pool pg, requester un principal authentifié et authorityTime un instant de confiance que vous fournissez. L’écouteur pool.on("error", ...) est obligatoire. Dans la branche catch, RedemptionSchemaError est l’erreur de configuration connue et toute autre exception est le résultat potentiellement inconnu décrit plus haut. reportIdleClientError, fixTheMigration et retryTheSameTicket représentent votre propre code ; aucune des deux branches n’exécute l’effet.

import { PostgresCapabilityRedemptionTransaction, RedemptionSchemaError } from "./src/storage/postgresCapabilityRedemptionTransaction.js";

pool.on("error", (error) => {
  reportIdleClientError(error);
});

const redemption = new PostgresCapabilityRedemptionTransaction(pool);
try {
  const result = await redemption.redeem(requester, command, authorityTime);
  if (result.ok) runEffectOnce(result.redemption);
  else refuseEffect(result.reason);
} catch (error) {
  if (error instanceof RedemptionSchemaError) fixTheMigration(error);
  else retryTheSameTicket();
}

Une rédemption peut ensuite être attestée : voir Authority Proof. Le SDK qui envelopperait ces appels est prévu et non commencé ; aujourd’hui, on les utilise comme ci-dessus.

Frontières de confiance

Ce que la rédemption croit, et ce qui en découle
FrontièreCe qui est cruCe qui en découle
IdentitéLe principal authentifié est affirmé par l’appelant.Seul un écart avec le demandeur de l’action est détecté. Un appelant qui affirme la bonne identité est cru.
HorlogeauthorityTime est fourni par l’appelant.Une horloge en retard peut racheter un billet longtemps après l’heure réelle. Un instant très lointain écrit dans le journal relève définitivement son plus haut niveau et fait ensuite répondre STALE_AUTHORITY_TIME aux appels dont l’horloge est correcte. Authority n’a aucune source de temps réel.
Rôle applicatifLe rôle applicatif PostgreSQL peut lire et insérer, pas modifier ni supprimer.Un écrivain ayant le droit d’insertion peut ajouter une fausse rédemption cohérente : elle est valide, car la validation contrôle la cohérence et non la provenance, et elle prend le billet à son détenteur. Il ne peut ni la modifier ni la supprimer.
Propriétaire de la base, superutilisateur, infrastructureHors périmètre.Ils peuvent modifier ou supprimer le journal.
Écrivains qui contournent le verrouDétectés, pas empêchés.La clé primaire et l’index unique refusent les collisions, et une séquence prise ou manquante fait échouer la rédemption en sécurité.
Effet externeNon couvert.REDEEMED autorise ; il ne fait pas que l’effet ait lieu, ait lieu une seule fois, ni soit annulé.

État de la revue

La rédemption n’a pas fait l’objet d’une revue indépendante. Ces énoncés suivent le dépôt au commit épinglé ; la spécification (invariants I26 à I31) reste la référence.

Sources au commit épinglé