smpebble/vlei-sandbox

Sandbox vLEI

Un modelo funcional de la cadena de confianza LEI verificable de GLEIF que se ejecuta en segundos sin infraestructura, más una ruta hacia la pila KERIA real cuando la simulación deja de ser suficiente.

Por qué existe

vLEI tiene un costo de entrada elevado que es mayoritariamente incidental. Los conceptos (registros de eventos clave KERI, credenciales encadenadas ACDC, codificación CESR, la jerarquía de gobernanza GLEIF) son aprendibles, pero el primer paso habitual es levantar contenedores Docker, resolver OOBIs y coordinar ceremonias multisig antes de poder emitir una sola credencial. Ese orden es inverso para cualquiera que intente averiguar si vLEI se adapta a su problema.

Este skill lo invierte. El modo simulado te proporciona firmas Ed25519 reales, codificación CESR real, identificadores auto-referenciados reales y aplicación real de operadores de borde, sin más dependencias que Python. Puedes diseñar un esquema de credenciales, romperlo deliberadamente y entender exactamente qué aceptará y qué no un verificador, en una tarde, en un portátil, sin conexión. Luego graduas.

Dos modos

	Simulado (predeterminado)	Real
Requiere	Python 3.8+	Docker Compose v2.23+
Inicio	instantáneo	~60s descarga de imágenes
Firmas	Ed25519 real	Ed25519 real
SAIDs / CESR	real	real
Testigos, OOBI, IPEX	modelados, omitidos	protocolo real
Ceremonias multisig, delegación	simplificadas	completas
Bueno para	diseño de credenciales, lógica de verificación, enseñanza, demostraciones	integración, comportamiento de protocolo, preproducción

Empieza en modo simulado a menos que el usuario necesite explícitamente comportamiento a nivel de protocolo. La mayoría de las preguntas de diseño de aplicaciones se responden más rápido ahí.

Primeros pasos

Todo se ejecuta a través de un solo script. Desde el directorio del skill:

python scripts/vlei_sandbox.py demo

Esto construye toda la cadena de confianza de seis pasos (GLEIF califica a un QVI, el QVI emite una credencial de Entidad Legal, la entidad autoriza un rol oficial, el QVI emite la credencial OOR, la entidad emite una credencial ECR directamente) y luego verifica el resultado de vuelta a la raíz de confianza, imprimiendo cada comprobación que realiza. Ejecútalo primero. La salida narrada es la explicación más rápida disponible de cómo encaja el ecosistema, y es una demo en vivo contundente.

Luego muestra qué se rompe:

python vlei_sandbox.py status                     # lista credenciales y SAIDs
python vlei_sandbox.py revoke --said <LE SAID>    # revoca la credencial de entidad
python vlei_sandbox.py verify --said <OOR SAID>   # ahora falla: la cadena colapsó

Esa secuencia (revocar una credencial y ver cómo falla todo lo que está debajo) transmite la idea central mejor que cualquier diagrama: la autoridad está vinculada, no es una afirmación aislada.

Referencia de comandos

Configuración

python vlei_sandbox.py init [--force]
python vlei_sandbox.py demo [--lei <18 chars>] [--person NOMBRE] [--role ROL] [--context-role ROL]
python vlei_sandbox.py status

Actores (controladores 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      # pre-rotación: el AID sobrevive

--root marca la raíz de confianza del ecosistema. --delegator produce un evento de inicio delegado (dip), reflejando cómo GLEIF delega AIDs a QVIs.

Credenciales

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 "Director Ejecutivo" --subject-aid <persona AID> --auth <LE SAID>
python vlei_sandbox.py issue --type oor      --issuer qvi --holder persona --lei <LEI> \
    --person "Jane Doe" --role "Director Ejecutivo" --auth <OOR AUTH SAID>
python vlei_sandbox.py issue --type ecr      --issuer le --holder persona --lei <LEI> \
    --person "Jane Doe" --context-role "Oficial de Financiación Comercial" --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

Añade --json a issue para imprimir el ACDC completo. Usa --data '{"clave":"valor"}' para atributos más allá de las banderas integradas.

La herramienta rechaza emisiones que romperían las reglas de gobernanza: una credencial sin borde autorizante, un borde hacia el tipo de credencial incorrecto, un LEI que falla su suma de verificación. Esos rechazos merecen ser demostrados; muestran que el modelo está aplicando algo, no decorando JSON.

Aritmética LEI (ISO 17442-1)

python vlei_sandbox.py lei make YZ83GD8L7GG84979J5     # -> YZ83GD8L7GG84979J516
python vlei_sandbox.py lei check YZ83GD8L7GG84979J516  # -> VÁLIDO

Diagramas

python vlei_sandbox.py chain --out chain.mmd    # Mermaid, listo para diapositivas o documentación

Entorno real

python vlei_sandbox.py real scaffold   # copia docker-compose.yaml en el proyecto
python vlei_sandbox.py real up
python vlei_sandbox.py real status
python vlei_sandbox.py real logs
python vlei_sandbox.py real down

Trabajando con un usuario

Ajusta la profundidad a lo que realmente intentan decidir.

"Explícame vLEI" — ejecuta demo y recorre su salida. No des una charla primero; los artefactos son más convincentes que la teoría, y la narración en la salida cubre los conceptos en el orden en que se necesitan.

"¿Puede vLEI resolver ?" — lee references/application-patterns.md antes de responder. La respuesta honesta suele ser "parcialmente", y las restricciones allí (coste del LEI, la diferencia entre verificado y confiable) importan más para una decisión real que las capacidades.

"Ayúdame a diseñar credenciales para X" — modela en modo simulado. Crea los actores, emite la cadena, luego atácala deliberadamente: intenta emitir sin autorización, encadena al tipo incorrecto, revoca un padre. Un diseño que sobrevive eso en modo simulado vale la pena construirlo para el entorno real.

"¿Cómo integro esto?" — lee references/real-environment.md. Empuja hacia mantener KERI en el borde: un servicio verificador que hable el protocolo, JSON ordinario aguas abajo.

"¿Mi X.509 / PKI existente es un atajo?" — sé directo al respecto. ISO 17442-2 (LEI en X.509) y 17442-3 (LEI en ACDC) son caminos paralelos, no una tubería de conversión. La PKI existente es genuinamente valiosa como fuente de aseguramiento de identidad que alimenta la verificación de representantes de la empresa por parte de un QVI, pero no existe una conversión de formato estandarizada, y plantearlo como tal no sobrevivirá al contacto con GLEIF o un regulador. references/trust-chain.md tiene el detalle.

Material de referencia

Léelos según sea necesario, no por adelantado:

• references/trust-chain.md — tipos de credenciales, anatomía de ACDC, operadores de borde, la lista de verificación completa del verificador, mapeo de la serie ISO 17442, SAIDs de esquema conocidos. Léelo antes de responder cualquier pregunta sobre estructura de credenciales o qué significa "verificado".
• references/real-environment.md — pila Docker, patrones de cliente Signify-TS, presentación IPEX, fricción conocida, el camino a producción. Léelo antes de tocar el modo real o escribir código de integración.
• references/application-patterns.md — cuatro patrones de aplicación viables, cómo extender más allá de los cinco tipos de credenciales estándar, lista de verificación de diseño de verificador, y las dos restricciones que vale la pena mencionar antes de que lo haga un escéptico. Léelo antes de delimitar o presentar una aplicación.

Notas de implementación

• Fidelidad. SAIDs, calificación CESR, operadores de borde, semántica de revocación TEL y pre-rotación se comportan según lo especificado. Las firmas son Ed25519 reales, verificadas en cada llamada verify.
• Algoritmo de resumen. El predeterminado de KERI es Blake3-256 (código CESR E). Blake3 no está en la biblioteca estándar de Python, por lo que el sandbox recurre a Blake2b-256 (código F) (también un código de resumen CESR válido). Por lo tanto, los identificadores comienzan con F en lugar de E a menos que el paquete opcional blake3 esté instalado, en cuyo caso coinciden exactamente con producción: pip install blake3. Menciona esto si un usuario nota la diferencia de prefijo; es una sustitución, no un error.
• Backend de firma. Usa cryptography o PyNaCl cuando estén presentes, y un Ed25519 puro en Python sin dependencias en caso contrario. init informa cuál se usa.
• Estado. Un único archivo legible .vlei/state.json en el directorio de trabajo. Inspecciónalo libremente (ver los KEL y TEL como JSON plano es instructivo). Contiene semillas de claves privadas, por lo que es un artefacto del sandbox y nunca debe confirmarse ni reutilizarse para nada real.
• Qué está deliberadamente ausente. Acuse de recibo de testigos, resolución de OOBI a través de la red, intercambio de mensajes IPEX, umbrales multisig, vigilantes. Estos son preocupaciones de protocolo que no cambian el diseño de credenciales. Recurre al modo real cuando se conviertan en la pregunta.

Portabilidad

El skill es Python plano más Markdown, sin dependencias de framework, por lo que funciona sin cambios en Claude Code, Codex, Gemini CLI o un terminal básico. Un agente que pueda leer archivos y ejecutar comandos de shell tiene todo lo que necesita. Si tu agente lee AGENTS.md en lugar de SKILL.md, ambos están presentes y apuntan al mismo contenido.