smpebble/vlei-sandbox

Was macht vlei-sandbox?

Ein funktionierendes Modell der GLEIF-verifiable-LEI-Vertrauenskette, das in Sekunden ohne Infrastruktur läuft, plus ein Pfad zum echten KERIA-Stack, wenn die Simulation nicht mehr ausreicht.

Warum es das gibt

vLEI hat eine steile Einstiegshürde, die meist nebensächlich ist. Die Konzepte – KERI-Key-Event-Logs, ACDC-Chained-Credentials, CESR-Encoding, die GLEIF-Governance-Hierarchie – sind lernbar, aber der übliche erste Schritt ist das Aufsetzen von Docker-Containern, das Auflösen von OOBIs und das Koordinieren von Multisig-Zeremonien, bevor man ein einziges Credential ausstellen kann. Diese Reihenfolge ist für jeden, der herausfinden will, ob vLEI zu seinem Problem passt, rückwärts gerichtet.

Dieser Skill kehrt es um. Der Mock-Modus liefert echte Ed25519-Signaturen, echtes CESR-Encoding, echte selbstadressierende Identifier und echte Edge-Operator-Durchsetzung – ohne Abhängigkeiten außer Python. Sie können ein Credential-Schema entwerfen, es absichtlich brechen und genau verstehen, was ein Verifizierer akzeptiert und was nicht – an einem Nachmittag, auf einem Laptop, offline. Dann steigen Sie auf.

Zwei Modi

	Mock (Standard)	Real
Erfordert	Python 3.8+	Docker Compose v2.23+
Start	sofort	~60s Image-Pull
Signaturen	echte Ed25519	echte Ed25519
SAIDs / CESR	echt	echt
Witnesses, OOBI, IPEX	wegfingiert	tatsächliches Protokoll
Multisig-, Delegationszeremonien	vereinfacht	vollständig
Geeignet für	Credential-Design, Verifizierungslogik, Lehre, Demos	Integration, Protokollverhalten, Pre-Production

Beginnen Sie im Mock-Modus, es sei denn, der Benutzer benötigt explizit Protokollverhalten. Die meisten Anwendungsdesignfragen werden dort schneller beantwortet.

Erste Schritte

Alles läuft über ein Skript. Aus dem Skill-Verzeichnis:

python scripts/vlei_sandbox.py demo

Dies baut die gesamte sechsstufige Vertrauenskette auf – GLEIF qualifiziert einen QVI, der QVI stellt ein Legal-Entity-Credential aus, die Entität autorisiert eine offizielle Rolle, der QVI stellt das OOR-Credential aus, die Entität stellt direkt ein ECR-Credential aus – und verifiziert dann das Ergebnis zurück zur Vertrauenswurzel, wobei jede Prüfung ausgegeben wird. Führen Sie dies zuerst aus. Die kommentierte Ausgabe ist die schnellste verfügbare Erklärung, wie das Ökosystem zusammenhängt, und sie ist eine starke Live-Demo.

Zeigen Sie dann, was bricht:

python vlei_sandbox.py status                     # Credentials und SAIDs auflisten
python vlei_sandbox.py revoke --said <LE SAID>    # Entity-Credential widerrufen
python vlei_sandbox.py verify --said <OOR SAID>   # schlägt jetzt fehl – die Kette ist zusammengebrochen

Diese Abfolge – ein Credential widerrufen und zusehen, wie alles darunter fehlschlägt – vermittelt die Kernidee besser als jedes Diagramm: Autorität ist verknüpft, nicht behauptet.

Befehlsreferenz

Setup

python vlei_sandbox.py init [--force]
python vlei_sandbox.py demo [--lei <18 Zeichen>] [--person NAME] [--role ROLLE] [--context-role ROLLE]
python vlei_sandbox.py status

Akteure (AID-Controller)

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: AID überlebt

--root markiert die Ökosystem-Vertrauenswurzel. --delegator erzeugt ein delegiertes Inceptions-Ereignis (dip), das widerspiegelt, wie GLEIF AIDs an QVIs delegiert.

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 <QVI SAID>
python vlei_sandbox.py issue --type oor-auth --issuer le --holder qvi --lei <LEI> \
    --person "Jane Doe" --role "Chief Executive Officer" --subject-aid <person AID> --auth <LE SAID>
python vlei_sandbox.py issue --type oor      --issuer qvi --holder person --lei <LEI> \
    --person "Jane Doe" --role "Chief Executive Officer" --auth <OOR AUTH SAID>
python vlei_sandbox.py issue --type ecr      --issuer le --holder person --lei <LEI> \
    --person "Jane Doe" --context-role "Trade Finance Officer" --auth <LE SAID>

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

Fügen Sie --json zu issue hinzu, um das vollständige ACDC auszugeben. Verwenden Sie --data '{"key":"value"}' für Attribute, die über die integrierten Flags hinausgehen.

Das Tool verweigert die Ausstellung, wenn die Governance-Regeln verletzt werden – ein Credential ohne autorisierende Kante, eine Kante zum falschen Credential-Typ, ein LEI, das die Prüfsumme nicht besteht. Diese Ablehnungen sind eine Vorführung wert; sie zeigen, dass das Modell etwas durchsetzt und nicht nur JSON dekoriert.

LEI-Arithmetik (ISO 17442-1)

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

Diagramme

python vlei_sandbox.py chain --out chain.mmd    # Mermaid, fertig für Folien oder Dokumente

Echte Umgebung

python vlei_sandbox.py real scaffold   # docker-compose.yaml in das Projekt kopieren
python vlei_sandbox.py real up
python vlei_sandbox.py real status
python vlei_sandbox.py real logs
python vlei_sandbox.py real down

Zusammenarbeit mit einem Benutzer

Passen Sie die Tiefe an das an, was der Benutzer tatsächlich entscheiden möchte.

„Erklären Sie mir vLEI“ – führen Sie demo aus und gehen Sie die Ausgabe durch. Halten Sie keinen Vortrag; die Artefakte sind überzeugender als die Theorie, und die Erläuterungen in der Ausgabe decken die Konzepte in der Reihenfolge ab, in der sie notwendig werden.

„Kann vLEI lösen?“ – lesen Sie references/application-patterns.md, bevor Sie antworten. Die ehrliche Antwort ist oft „teilweise“, und die dort genannten Einschränkungen (LEI-Kosten, der Unterschied zwischen verifiziert und vertrauenswürdig) sind für eine echte Entscheidung wichtiger als die Fähigkeiten.

„Helfen Sie mir, Credentials für X zu entwerfen“ – modellieren Sie es im Mock-Modus. Erstellen Sie die Akteure, stellen Sie die Kette aus, greifen Sie sie dann absichtlich an: Versuchen Sie, ohne Autorisierung auszustellen, an den falschen Typ anzuketten, ein übergeordnetes Element zu widerrufen. Ein Design, das dies im Mock-Modus übersteht, ist es wert, für die Praxis gebaut zu werden.

„Wie integriere ich das?“ – lesen Sie references/real-environment.md. Drängen Sie darauf, KERI am Rande zu halten: ein Verifizierer-Dienst, der das Protokoll spricht, gewöhnliches JSON flussabwärts.

„Ist mein X.509 / meine bestehende PKI ein Shortcut?“ – seien Sie direkt. ISO 17442-2 (LEI in X.509) und 17442-3 (LEI in ACDC) sind parallele Pfade, keine Konvertierungspipeline. Die bestehende PKI ist als Identitätsprüfungsquelle, die die Überprüfung von Unternehmensvertretern durch einen QVI speist, wirklich wertvoll, aber es gibt kein standardisiertes Formatkonvertierung, und es als eine solche darzustellen, wird den Kontakt mit GLEIF oder einer Aufsichtsbehörde nicht überstehen. references/trust-chain.md enthält die Details.

Referenzmaterial

Lesen Sie diese nach Bedarf, nicht im Voraus:

• references/trust-chain.md – Credential-Typen, ACDC-Anatomie, Edge-Operatoren, die vollständige Verifizierungscheckliste, ISO-17442-Serie-Zuordnung, bekannte Schema-SAIDs. Lesen Sie, bevor Sie eine Frage zur Credential-Struktur oder dazu beantworten, was „verifiziert“ bedeutet.
• references/real-environment.md – Docker-Stack, Signify-TS-Client-Muster, IPEX-Präsentation, bekannte Reibungspunkte, der Weg in die Produktion. Lesen Sie, bevor Sie den real-Modus anfassen oder Integrationscode schreiben.
• references/application-patterns.md – vier brauchbare Anwendungsmuster, wie man über die fünf Standard-Credential-Typen hinausgeht, Verifizierer-Design-Checkliste und die zwei Einschränkungen, die erwähnenswert sind, bevor ein Skeptiker sie aufbringt. Lesen Sie, bevor Sie eine Anwendung eingrenzen oder pitchen.

Implementierungshinweise

• Genauigkeit. SAIDs, CESR-Qualifikation, Edge-Operatoren, TEL-Widerrufs-Semantik und Prä-Rotation verhalten sich wie spezifiziert. Signaturen sind echte Ed25519, die bei jedem verify-Aufruf verifiziert werden.
• Digest-Algorithmus. KERIs Standard ist Blake3-256 (CESR-Code E). Blake3 ist nicht in der Python-Standardbibliothek enthalten, daher fällt die Sandbox auf Blake2b-256 (Code F) zurück – ebenfalls ein gültiger CESR-Digest-Code. Identifier beginnen daher mit F statt E, es sei denn, das optionale Paket blake3 ist installiert – in diesem Fall entsprechen sie der Produktion genau: pip install blake3. Erwähnen Sie dies, wenn einem Benutzer der Unterschied im Präfix auffällt; es ist eine Substitution, kein Fehler.
• Signing-Backend. Verwendet cryptography oder PyNaCl, falls vorhanden, und ansonsten ein abhängigkeitsfreies reines Python-Ed25519. init gibt an, welches verwendet wird.
• Zustand. Eine einzelne lesbare .vlei/state.json im Arbeitsverzeichnis. Sehen Sie sie ruhig ein – die KELs und TELs als einfaches JSON zu sehen, ist lehrreich. Sie enthält private Schlüssel-Seeds, ist also ein Sandbox-Artefakt und sollte niemals committet oder für etwas Reales wiederverwendet werden.
• Was bewusst fehlt. Witness-Quittierungen, OOBI-Auflösung über das Netzwerk, IPEX-Nachrichtenaustausch, Multisig-Schwellenwerte, Watcher. Dies sind Protokollbelange, die das Credential-Design nicht ändern. Greifen Sie auf den real-Modus zu, wenn diese zur Frage werden.

Portabilität

Der Skill ist reines Python plus Markdown, ohne Framework-Abhängigkeiten, und funktioniert daher unverändert in Claude Code, Codex, Gemini CLI oder einem einfachen Terminal. Ein Agent, der Dateien lesen und Shell-Befehle ausführen kann, hat alles, was er braucht. Wenn Ihr Agent AGENTS.md statt SKILL.md liest, sind beide vorhanden und verweisen auf denselben Inhalt.