smpebble/vlei-sandbox

Sandbox vLEI

Um modelo funcional da cadeia de confiança do LEI verificável GLEIF que é executado em segundos com nenhuma infraestrutura, além de um caminho para a pilha KERIA real quando a simulação não for mais suficiente.

Por que isso existe

O vLEI tem um custo de entrada alto que é, em sua maior parte, incidental. Os conceitos -- registros de eventos de chave KERI, credenciais encadeadas ACDC, codificação CESR, a hierarquia de governança GLEIF -- são aprendíveis, mas o primeiro passo usual é levantar contêineres Docker, resolver OOBIs e coordenar cerimônias multisig antes de conseguir emitir uma única credencial. Essa ordenação é invertida para qualquer um que esteja tentando descobrir se o vLEI se adequa ao seu problema.

Este skill inverte isso. O modo simulado fornece assinaturas Ed25519 reais, codificação CESR real, identificadores auto-referenciáveis reais e aplicação real de operadores de borda, com zero dependências além do Python. Você pode projetar um esquema de credenciais, quebrá-lo deliberadamente e entender exatamente o que um verificador aceitará ou não -- em uma tarde, em um laptop, offline. Então você evolui.

Dois modos

	Simulado (padrão)	Real
Requer	Python 3.8+	Docker Compose v2.23+
Inicialização	instantânea	~60s para baixar imagem
Assinaturas	Ed25519 real	Ed25519 real
SAIDs / CESR	real	real
Testemunhas, OOBI, IPEX	modelado como ausente	protocolo real
Cerimônias multisig, delegação	simplificadas	completas
Bom para	design de credenciais, lógica de verificador, ensino, demonstrações	integração, comportamento de protocolo, pré-produção

Inicie no modo simulado, a menos que o usuário precise explicitamente de comportamento de nível de protocolo. A maioria das questões de design de aplicativos é respondida mais rapidamente lá.

Primeiros passos

Tudo é executado através de um único script. Do diretório do skill:

python scripts/vlei_sandbox.py demo

Isso constrói toda a cadeia de confiança de seis etapas -- GLEIF qualifica um QVI, o QVI emite uma credencial de Entidade Legal, a entidade autoriza uma função oficial, o QVI emite a credencial OOR, a entidade emite uma credencial ECR diretamente -- e depois verifica o resultado de volta à raiz de confiança, imprimindo cada verificação que realiza. Execute-o primeiro. A saída narrada é a explicação mais rápida disponível de como o ecossistema se encaixa, e é uma demonstração ao vivo forte.

Em seguida, mostre o que quebra:

python vlei_sandbox.py status                     # listar credenciais e SAIDs
python vlei_sandbox.py revoke --said <LE SAID>    # revogar a credencial da entidade
python vlei_sandbox.py verify --said <OOR SAID>   # agora falha -- a cadeia colapsou

Essa sequência -- revogar uma credencial e ver tudo abaixo dela falhar -- fixa a ideia central melhor do que qualquer diagrama: a autoridade é vinculada, não afirmada.

Referência de comandos

Configuração

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

Atores (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      # pré-rotação: AID sobrevive

--root marca a raiz de confiança do ecossistema. --delegator produz um evento de criação delegada (dip), espelhando como o GLEIF delega AIDs para QVIs.

Credenciais

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

Adicione --json a issue para imprimir o ACDC completo. Use --data '{"key":"value"}' para atributos além das flags integradas.

A ferramenta recusa a emissão que quebraria as regras de governança -- uma credencial sem uma borda autorizadora, uma borda para o tipo de credencial errado, um LEI que falha seu checksum. Essas recusas valem a pena serem demonstradas; elas mostram que o modelo está aplicando algo, em vez de decorar JSON.

Aritmética de LEI (ISO 17442-1)

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

Diagramas

python vlei_sandbox.py chain --out chain.mmd    # Mermaid, pronto para slides ou documentos

Ambiente real

python vlei_sandbox.py real scaffold   # copiar docker-compose.yaml para o projeto
python vlei_sandbox.py real up
python vlei_sandbox.py real status
python vlei_sandbox.py real logs
python vlei_sandbox.py real down

Trabalhando com um usuário

Combine a profundidade com o que ele está realmente tentando decidir.

"Explique o vLEI para mim" -- execute demo e percorra sua saída. Não dê uma palestra primeiro; os artefatos são mais convincentes do que a teoria, e a narração na saída cobre os conceitos na ordem em que se tornam necessários.

"O vLEI pode resolver ?" -- leia references/application-patterns.md antes de responder. A resposta honesta é frequentemente "parcialmente", e as restrições lá (custo do LEI, a diferença entre verificado e confiável) importam mais para uma decisão real do que os recursos.

"Ajude-me a projetar credenciais para X" -- modele no modo simulado. Crie os atores, emita a cadeia e, em seguida, ataque-a deliberadamente: tente emitir sem autorização, encadear ao tipo errado, revogar um pai. Um design que sobreviver a isso no modo simulado vale a pena ser construído para o real.

"Como faço para integrar isso?" -- leia references/real-environment.md. Empurre para manter o KERI na borda: um serviço verificador falando o protocolo, JSON comum downstream.

"Meu X.509 / PKI existente é um atalho?" -- seja direto sobre isso. ISO 17442-2 (LEI em X.509) e 17442-3 (LEI em ACDC) são caminhos paralelos, não um pipeline de conversão. PKI existente é genuinamente valioso como uma fonte de garantia de identidade que alimenta a verificação de representantes da empresa por um QVI, mas não há conversão de formato padronizada, e enquadrá-la como tal não sobreviverá ao contato com o GLEIF ou um regulador. references/trust-chain.md tem os detalhes.

Material de referência

Leia estes conforme necessário, não antecipadamente:

• references/trust-chain.md -- tipos de credenciais, anatomia ACDC, operadores de borda, a lista de verificação completa do verificador, mapeamento da série ISO 17442, SAIDs de esquema conhecidos. Leia antes de responder qualquer pergunta sobre estrutura de credenciais ou o que "verificado" significa.
• references/real-environment.md -- pilha Docker, padrões de cliente Signify-TS, apresentação IPEX, atritos conhecidos, o caminho para a produção. Leia antes de tocar no modo real ou escrever código de integração.
• references/application-patterns.md -- quatro padrões de aplicação viáveis, como estender além dos cinco tipos de credenciais padrão, lista de verificação de design de verificador e as duas restrições que vale a pena levantar antes que um cético o faça. Leia antes de escopar ou apresentar um aplicativo.

Notas de implementação

• Fidelidade. SAIDs, qualificação CESR, operadores de borda, semântica de revogação TEL e pré-rotação se comportam conforme especificado. As assinaturas são Ed25519 reais, verificadas em cada chamada verify.
• Algoritmo de digestão. O padrão do KERI é Blake3-256 (código CESR E). Blake3 não está na biblioteca padrão do Python, então o sandbox usa Blake2b-256 como fallback (código F) -- também um código de digestão CESR válido. Os identificadores, portanto, começam com F em vez de E, a menos que o pacote opcional blake3 esteja instalado; nesse caso, eles correspondem exatamente à produção: pip install blake3. Mencione isso se um usuário notar a diferença de prefixo; é uma substituição, não um erro.
• Backend de assinatura. Usa cryptography ou PyNaCl quando presente, e um Ed25519 Python puro sem dependências caso contrário. init informa qual.
• Estado. Um único arquivo .vlei/state.json legível no diretório de trabalho. Inspecione-o livremente -- ver os KELs e TELs como JSON simples é instrutivo. Ele contém sementes de chave privada, portanto é um artefato do sandbox e nunca deve ser commitado ou reutilizado para algo real.
• O que está deliberadamente ausente. Recebimento de testemunhas, resolução de OOBI pela rede, troca de mensagens IPEX, limites multisig, observadores. Estas são preocupações de protocolo que não alteram o design da credencial. Recorra ao modo real quando elas se tornarem a questão.

Portabilidade

O skill é Python simples mais Markdown, sem dependências de framework, portanto funciona inalterado no Claude Code, Codex, Gemini CLI ou em um terminal simples. Um agente que pode ler arquivos e executar comandos de shell tem tudo que precisa. Se seu agente lê AGENTS.md em vez de SKILL.md, ambos estão presentes e apontam para o mesmo conteúdo.