smpebble/vlei-sandbox

Bac à sable vLEI

Un modèle fonctionnel de la chaîne de confiance LEI vérifiable de GLEIF qui s'exécute en quelques secondes sans infrastructure, plus un chemin vers la pile KERIA réelle lorsque la simulation ne suffit plus.

Pourquoi ça existe

Le vLEI a un coût d'entrée élevé qui est surtout accessoire. Les concepts — journaux d'événements de clé KERI, credentials ACDC chaînés, encodage CESR, hiérarchie de gouvernance GLEIF — sont apprenables, mais la première étape habituelle est de monter des conteneurs Docker, de résoudre des OOBIs et de coordonner des cérémonies multi-signatures avant de pouvoir émettre un seul credential. Cet ordre est inversé pour quiconque essaie de déterminer si le vLEI correspond à son problème.

Ce skill inverse la tendance. Le mode mock vous donne de véritables signatures Ed25519, un véritable encodage CESR, de véritables identifiants auto-adressants et une véritable application des opérateurs de bordure, avec zéro dépendance au-delà de Python. Vous pouvez concevoir un schéma de credential, le casser délibérément et comprendre exactement ce qu'un vérificateur acceptera ou non — en un après-midi, sur un ordinateur portable, hors ligne. Ensuite, vous passez à la vitesse supérieure.

Deux modes

	Mock (par défaut)	Réel
Nécessite	Python 3.8+	Docker Compose v2.23+
Démarrage	instantané	~60s de téléchargement d'image
Signatures	Ed25519 réelles	Ed25519 réelles
SAIDs / CESR	réels	réels
Témoins, OOBI, IPEX	modélisés	protocole réel
Cérémonies multi-signatures, délégation	simplifiées	complètes
Utile pour	conception de credentials, logique de vérification, enseignement, démos	intégration, comportement protocolaire, pré-production

Commencez en mode mock sauf si l'utilisateur a explicitement besoin d'un comportement au niveau du protocole. La plupart des questions de conception d'application y trouvent une réponse plus rapidement.

Pour commencer

Tout passe par un seul script. Depuis le répertoire du skill :

python scripts/vlei_sandbox.py demo

Ceci construit toute la chaîne de confiance en six étapes — GLEIF qualifie un QVI, le QVI émet un credential d'entité légale, l'entité autorise un rôle officiel, le QVI émet le credential OOR, l'entité émet directement un credential ECR — puis vérifie le résultat jusqu'à la racine de confiance, en affichant chaque vérification qu'il effectue. Exécutez-le en premier. La sortie narrée est l'explication la plus rapide disponible de la façon dont l'écosystème s'emboîte, et c'est une démonstration en direct solide.

Montrez ensuite ce qui casse :

python vlei_sandbox.py status                     # liste les credentials et SAIDs
python vlei_sandbox.py revoke --said <SAID_LE>    # révoque le credential d'entité
python vlei_sandbox.py verify --said <SAID_OOR>   # échoue maintenant — la chaîne s'est effondrée

Cette séquence — révoquer un credential et regarder tout ce qui se trouve en dessous échouer — fait comprendre l'idée centrale mieux que n'importe quel diagramme : l'autorité est liée, pas affirmée.

Référence des commandes

Configuration

python vlei_sandbox.py init [--force]
python vlei_sandbox.py demo [--lei <18 caractères>] [--person NOM] [--role RÔLE] [--context-role RÔLE]
python vlei_sandbox.py status

Acteurs (contrôleurs AID)

python vlei_sandbox.py actor add --alias gleif --registry gleifRegistry --root
python vlei_sandbox.py actor add --alias qvi --registry qviRegistry --delegator gleif
python vlei_sandbox.py actor list
python vlei_sandbox.py actor rotate --alias qvi      # pré-rotation : l'AID survit

--root marque la racine de confiance de l'écosystème. --delegator produit un événement de création déléguée (dip), reflétant la façon dont GLEIF délègue des AIDs aux QVIs.

Credentials

python vlei_sandbox.py issue --type qvi      --issuer gleif --holder qvi --lei <LEI>
python vlei_sandbox.py issue --type le       --issuer qvi --holder le --lei <LEI> --auth <SAID_QVI>
python vlei_sandbox.py issue --type oor-auth --issuer le --holder qvi --lei <LEI> \
    --person "Jane Doe" --role "Directeur Général" --subject-aid <AID personne> --auth <SAID_LE>
python vlei_sandbox.py issue --type oor      --issuer qvi --holder person --lei <LEI> \
    --person "Jane Doe" --role "Directeur Général" --auth <SAID_OOR_AUTH>
python vlei_sandbox.py issue --type ecr      --issuer le --holder person --lei <LEI> \
    --person "Jane Doe" --context-role "Responsable du Financement du Commerce" --auth <SAID_LE>

python vlei_sandbox.py revoke --said <SAID>
python vlei_sandbox.py verify --said <SAID>
python vlei_sandbox.py present --said <SAID> --out presentation.json

Ajoutez --json à issue pour imprimer l'ACDC complet. Utilisez --data '{"clé":"valeur"}' pour les attributs au-delà des indicateurs intégrés.

L'outil refuse les émissions qui enfreindraient les règles de gouvernance — un credential sans bordure autorisée, une bordure vers le mauvais type de credential, un LEI qui échoue à sa somme de contrôle. Ces refus valent la peine d'être démontrés ; ils montrent que le modèle applique quelque chose plutôt que de décorer du JSON.

Arithmétique LEI (ISO 17442-1)

python vlei_sandbox.py lei make YZ83GD8L7GG84979J5     # -> YZ83GD8L7GG84979J516
python vlei_sandbox.py lei check YZ83GD8L7GG84979J516  # -> VALIDE

Diagrammes

python vlei_sandbox.py chain --out chain.mmd    # Mermaid, prêt pour les diapositives ou la documentation

Environnement réel

python vlei_sandbox.py real scaffold   # copie docker-compose.yaml dans le projet
python vlei_sandbox.py real up
python vlei_sandbox.py real status
python vlei_sandbox.py real logs
python vlei_sandbox.py real down

Travailler avec un utilisateur

Adaptez la profondeur à ce qu'il essaie réellement de décider.

« Expliquez-moi le vLEI » — exécutez demo et parcourez sa sortie. Ne faites pas de cours d'abord ; les artefacts sont plus convaincants que la théorie, et la narration dans la sortie couvre les concepts dans l'ordre où ils deviennent nécessaires.

« Le vLEI peut-il résoudre <problème> ? » — lisez references/application-patterns.md avant de répondre. La réponse honnête est souvent « en partie », et les contraintes qui y figurent (coût du LEI, différence entre vérifié et digne de confiance) importent davantage pour une décision réelle que les capacités.

« Aidez-moi à concevoir des credentials pour X » — modélisez-le en mode mock. Créez les acteurs, émettez la chaîne, puis attaquez-la délibérément : essayez d'émettre sans autorisation, enchaînez vers le mauvais type, révoquez un parent. Une conception qui survit à cela en mode mock mérite d'être construite pour de vrai.

« Comment intégrer cela ? » — lisez references/real-environment.md. Encouragez à maintenir KERI en périphérie : un service de vérification unique parlant le protocole, du JSON ordinaire en aval.

« Mon X.509 / PKI existant est-il un raccourci ? » — soyez franc à ce sujet. ISO 17442-2 (LEI dans X.509) et 17442-3 (LEI dans ACDC) sont des chemins parallèles, pas un pipeline de conversion. La PKI existante est véritablement précieuse comme source d'assurance d'identité alimentant la vérification des représentants d'entreprise par un QVI, mais il n'existe pas de conversion de format standardisée, et la présenter comme telle ne survivra pas au contact avec GLEIF ou un régulateur. references/trust-chain.md contient les détails.

Documentation de référence

Lisez-les selon les besoins plutôt qu'au préalable :

• references/trust-chain.md — types de credentials, anatomie de l'ACDC, opérateurs de bordure, la liste de contrôle complète du vérificateur, correspondance avec la série ISO 17442, SAIDs de schémas bien connus. À lire avant de répondre à toute question sur la structure des credentials ou ce que signifie « vérifié ».
• references/real-environment.md — pile Docker, modèles d'utilisation de Signify-TS, présentation IPEX, frictions connues, chemin vers la production. À lire avant de toucher au mode real ou d'écrire du code d'intégration.
• references/application-patterns.md — quatre modèles d'application fonctionnels, comment étendre au-delà des cinq types de credentials standard, liste de contrôle de conception du vérificateur, et les deux contraintes à soulever avant qu'un sceptique ne le fasse. À lire avant de cadrer ou de présenter une application.

Notes d'implémentation

• Fidélité. Les SAIDs, la qualification CESR, les opérateurs de bordure, la sémantique de révocation TEL et la pré-rotation se comportent comme spécifié. Les signatures sont Ed25519 réelles, vérifiées à chaque appel verify.
• Algorithme de hachage. La valeur par défaut de KERI est Blake3-256 (code CESR E). Blake3 ne fait pas partie de la bibliothèque standard Python, donc le bac à sable utilise Blake2b-256 (code F) comme solution de repli — également un code de hachage CESR valide. Les identifiants commencent donc par F plutôt que par E sauf si le paquet optionnel blake3 est installé, auquel cas ils correspondent exactement à la production : pip install blake3. Mentionnez-le si un utilisateur remarque la différence de préfixe ; c'est une substitution, pas une erreur.
• Backend de signature. Utilise cryptography ou PyNaCl lorsqu'ils sont présents, et une implémentation Ed25519 pure Python sans dépendance sinon. init indique lequel est utilisé.
• État. Un seul fichier lisible .vlei/state.json dans le répertoire de travail. Inspectez-le librement — voir les KELs et TELs en JSON brut est instructif. Il contient des graines de clés privées, c'est donc un artefact de bac à sable et ne doit jamais être commité ou réutilisé pour quoi que ce soit de réel.
• Ce qui est délibérément absent. L'accusé de réception des témoins, la résolution OOBI sur le réseau, l'échange de messages IPEX, les seuils multi-signatures, les observateurs. Ce sont des préoccupations protocolaires qui ne changent pas la conception des credentials. Utilisez le mode real lorsqu'elles deviennent la question.

Portabilité

Le skill est du Python pur plus du Markdown, sans dépendances framework, donc il fonctionne sans modification dans Claude Code, Codex, Gemini CLI ou un terminal nu. Un agent capable de lire des fichiers et d'exécuter des commandes shell a tout ce dont il a besoin. Si votre agent lit AGENTS.md plutôt que SKILL.md, les deux sont présents et pointent vers le même contenu.