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
- Émettre.
issue()reçoit le demandeur authentifié, une clé d’idempotence du client, une commande nommant unaction_idet unenforcement_point_id, et unauthorityTimeexplicite. Si les validateurs du moteur acceptent, elle enregistre un événementCAPABILITY_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 avecREQUESTER_MISMATCH,STALE_AUTHORITY_TIMEouCAPACITY_EXCEEDED. - Racheter. Juste avant l’effet, le point d’application appelle
redeem()avec le principal authentifié, une commande et unauthorityTimeexplicite. 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. - Exécuter. Seulement si
redeem()renvoieok: 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é : unauthorityTimestrictement antérieur àexpires_atest valide, sinonEXPIRED. - 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 unarguments_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. authorityTimen’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
| Résultat | Événement écrit | Billet consommé | L’effet peut s’exécuter | L’appelant doit |
|---|---|---|---|---|
REDEEMED | oui, juste après la décision | oui | oui | exé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_TIME | non | non | non | corriger la cause, ou autoriser de nouveau |
ALREADY_REDEEMED, REDEMPTION_COLLISION | non, pas par cet appel | oui, par un autre appel | non | ne pas réessayer : cet appel n’a jamais autorisé l’effet |
CONCURRENT_WRITE_DETECTED, en mémoire | oui, mais pas juste après la décision | oui | non | autoriser de nouveau ; cela peut se heurter à CAPACITY_EXCEEDED |
CONCURRENT_WRITE_DETECTED, sur PostgreSQL | non, annulé | non | non | réessayer : la décision est reprise sur le nouveau journal |
RedemptionSchemaError, sur PostgreSQL | non, levée avant toute écriture | non | non | corriger la migration, puis réessayer le même billet |
| toute autre exception, sur PostgreSQL | inconnu | inconnu | non | ré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()renvoieok: falseavec 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.
RedemptionSchemaErrorest 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 :
- Réessayer le même billet.
REDEEMEDsignifie que la première tentative n’avait pas été validée : exécuter l’effet une fois.ALREADY_REDEEMEDsignifie 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
| Frontière | Ce qui est cru | Ce 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. |
| Horloge | authorityTime 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 applicatif | Le 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, infrastructure | Hors périmètre. | Ils peuvent modifier ou supprimer le journal. |
| Écrivains qui contournent le verrou | Dé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 externe | Non 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.