vLEI 샌드박스은(는) 무엇을 하나요?

인프라 없이 몇 초 만에 실행되는 GLEIF 검증 가능 LEI 신뢰 체인의 실제 작동 모델이며, 시뮬레이션으로 충분하지 않을 때 실제 KERIA 스택으로의 경로도 제공합니다.

존재 이유

vLEI는 대부분 부수적인 요소로 인해 진입 비용이 높습니다. KERI 키 이벤트 로그, ACDC 체인 자격 증명, CESR 인코딩, GLEIF 거버넌스 계층 구조와 같은 개념 자체는 학습 가능하지만, 일반적인 첫 단계는 Docker 컨테이너를 띄우고, OOBI를 해결하고, 다중 서명 세션을 조정한 후에야 단일 자격 증명을 발급할 수 있습니다. 이러한 순서는 vLEI가 자신의 문제에 적합한지 확인하려는 사람에게는 역순입니다.

이 스킬은 그 순서를 뒤집습니다. Mock 모드는 Python 외에는 어떤 종속성도 없이 실제 Ed25519 서명, 실제 CESR 인코딩, 실제 자기 주소 지정 식별자, 실제 에지 연산자 적용을 제공합니다. 자격 증명 체계를 설계하고, 의도적으로 손상시키며, 검증자가 무엇을 수용하고 수용하지 않을지 정확히 이해할 수 있습니다 — 노트북에서, 오프라인으로, 오후 만에 가능합니다. 그런 다음 실제 환경으로 넘어갑니다.

두 가지 모드

	Mock (기본값)	실제(Real)
필요 조건	Python 3.8+	Docker Compose v2.23+
시작 시간	즉시	~60초 이미지 풀
서명	실제 Ed25519	실제 Ed25519
SAID / CESR	실제	실제
Witness, OOBI, IPEX	모델링되어 생략됨	실제 프로토콜
다중 서명, 위임 절차	단순화됨	전체
적합한 용도	자격 증명 설계, 검증자 로직, 교육, 데모	통합, 프로토콜 동작, 프로덕션 전 단계

사용자가 명시적으로 프로토콜 수준 동작을 필요로 하지 않는 한 Mock 모드로 시작하십시오. 대부분의 애플리케이션 설계 질문은 Mock 모드에서 더 빠르게 답을 얻을 수 있습니다.

시작하기

모든 것은 하나의 스크립트로 실행됩니다. 스킬 디렉토리에서 다음을 실행하십시오:

python scripts/vlei_sandbox.py demo

이 명령은 6단계 전체 신뢰 체인(GLEIF가 QVI를 인증하고, QVI가 법인 자격 증명을 발급하고, 법인이 공식 역할을 승인하고, QVI가 OOR 자격 증명을 발급하고, 법인이 직접 ECR 자격 증명을 발급)을 구축한 후, 결과를 신뢰 루트까지 검증하며 수행하는 모든 검사를 출력합니다. 먼저 실행해보십시오. 해설이 포함된 출력은 생태계가 어떻게 구성되는지 가장 빠르게 설명해주는 방법이며, 훌륭한 라이브 데모이기도 합니다.

그런 다음 무엇이 깨지는지 보여주십시오:

python vlei_sandbox.py status                     # 자격 증명 및 SAID 나열
python vlei_sandbox.py revoke --said <LE SAID>    # 법인 자격 증명 철회
python vlei_sandbox.py verify --said <OOR SAID>   # 이제 실패 — 체인이 무너짐

하나의 자격 증명을 철회하고 그 아래 모든 것이 실패하는 것을 지켜보는 이 절차는 어떤 다이어그램보다 핵심 아이디어를 잘 전달합니다: 권한은 연결되어 있으며, 단언되는 것이 아닙니다.

명령어 참조

설정

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

행위자 (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      # 사전 회전: AID 유지

--root는 생태계 신뢰 루트를 표시합니다. --delegator는 위임된 시작(dip) 이벤트를 생성하며, GLEIF가 QVI에 AID를 위임하는 방식을 반영합니다.

자격 증명

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

issue에 --json을 추가하면 전체 ACDC를 출력합니다. 내장 플래그를 넘는 속성은 --data '{"key":"value"}'를 사용하십시오.

도구는 거버넌스 규칙을 위반하는 발급을 거부합니다 — 승인 에지가 없는 자격 증명, 잘못된 자격 증명 유형에 대한 에지, 체크섬에 실패하는 LEI 등. 이러한 거부는 시연할 가치가 있습니다; 모델이 단순히 JSON을 장식하는 것이 아니라 무언가를 강제하고 있음을 보여줍니다.

LEI 연산 (ISO 17442-1)

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

다이어그램

python vlei_sandbox.py chain --out chain.mmd    # Mermaid, 슬라이드나 문서에 바로 사용 가능

실제 환경

python vlei_sandbox.py real scaffold   # docker-compose.yaml을 프로젝트로 복사
python vlei_sandbox.py real up
python vlei_sandbox.py real status
python vlei_sandbox.py real logs
python vlei_sandbox.py real down

사용자와 함께 작업하기

사용자가 실제로 결정하려는 내용에 맞춰 깊이를 조정하십시오.

"vLEI에 대해 설명해주세요" — demo를 실행하고 출력을 함께 살펴보십시오. 먼저 이론을 설명하지 마십시오; 산출물이 이론보다 더 설득력 있고, 출력의 내레이션이 필요한 순서대로 개념을 다룹니다.

"vLEI가 <문제>를 해결할 수 있나요?" — 답변하기 전에 references/application-patterns.md를 읽으십시오. 솔직한 답은 종종 "부분적으로"이며, 그곳의 제약 조건(LEI 비용, 검증됨과 신뢰할 수 있음의 차이)이 실제 결정에 있어 기능보다 더 중요합니다.

"X를 위한 자격 증명 설계를 도와주세요" — Mock 모드에서 모델링하십시오. 행위자를 생성하고, 체인을 발급한 후 의도적으로 공격하십시오: 승인 없이 발급 시도, 잘못된 유형에 연결, 상위 자격 증명 철회. Mock 모드에서 이러한 공격을 견디는 설계는 실제로 구축할 가치가 있습니다.

"이것을 어떻게 통합하나요?" — references/real-environment.md를 읽으십시오. KERI를 에지에 유지하는 방향으로 안내하십시오: 프로토콜을 말하는 단일 검증자 서비스, 하위 스트림은 일반 JSON 사용.

"제 X.509 / 기존 PKI가 지름길인가요?" — 솔직하게 답하십시오. ISO 17442-2 (X.509의 LEI)와 17442-3 (ACDC의 LEI)은 변환 파이프라인이 아닌 병렬 경로입니다. 기존 PKI는 QVI의 회사 대표자 검증을 위한 신원 확인 소스로서 진정으로 가치 있지만, 표준화된 형식 변환은 없으며, 이를 변환으로 프레이밍하는 것은 GLEIF나 규제 기관을 만나면 유지되지 않습니다. references/trust-chain.md에 자세한 내용이 있습니다.

참고 자료

미리 읽기보다는 필요할 때 읽으십시오:

references/trust-chain.md — 자격 증명 유형, ACDC 구조, 에지 연산자, 전체 검증자 체크리스트, ISO 17442 시리즈 매핑, 잘 알려진 스키마 SAID. 자격 증명 구조나 "검증됨"의 의미에 대한 질문에 답변하기 전에 읽으십시오.
references/real-environment.md — Docker 스택, Signify-TS 클라이언트 패턴, IPEX 프레젠테이션, 알려진 마찰점, 프로덕션 경로. real 모드를 다루거나 통합 코드를 작성하기 전에 읽으십시오.
references/application-patterns.md — 네 가지 실용적인 애플리케이션 패턴, 5가지 표준 자격 증명 유형을 넘어 확장하는 방법, 검증자 설계 체크리스트, 회의론자가 제기하기 전에 언급할 가치가 있는 두 가지 제약 조건. 애플리케이션 범위를 정하거나 제안하기 전에 읽으십시오.

구현 참고 사항

정확성. SAID, CESR 인증, 에지 연산자, TEL 철회 의미론, 사전 회전 모두 명세대로 동작합니다. 서명은 실제 Ed25519이며, 모든 verify 호출 시 검증됩니다.
다이제스트 알고리즘. KERI의 기본값은 Blake3-256 (CESR 코드 E)입니다. Blake3는 Python 표준 라이브러리에 없으므로, 샌드박스는 Blake2b-256 (코드 F)으로 대체됩니다 — 이것도 유효한 CESR 다이제스트 코드입니다. 따라서 식별자는 선택적 blake3 패키지가 설치되지 않은 경우 E 대신 F로 시작합니다. 설치 시 프로덕션과 정확히 일치합니다: pip install blake3. 사용자가 접두사 차이를 발견하면 언급하십시오; 대체일 뿐 오류가 아닙니다.
서명 백엔드. cryptography 또는 PyNaCl이 있으면 사용하고, 없으면 종속성 없는 순수 Python Ed25519를 사용합니다. init이 어떤 것이 사용되는지 보고합니다.
상태. 작업 디렉토리에 단일 읽기 가능한 .vlei/state.json 파일이 생성됩니다. 자유롭게 검사하십시오 — KEL과 TEL을 일반 JSON으로 보는 것은 교육적입니다. 개인 키 시드를 포함하므로 샌드박스 산출물이며, 커밋하거나 실제 용도로 재사용해서는 안 됩니다.
의도적으로 생략된 것. Witness 영수증, 유선 OOBI 해결, IPEX 메시지 교환, 다중 서명 임계값, Watcher. 이들은 자격 증명 설계를 변경하지 않는 프로토콜 고려 사항입니다. 이것들이 질문이 될 때 real 모드를 사용하십시오.

이식성

이 스킬은 프레임워크 종속성 없이 순수 Python과 Markdown으로 작성되어, Claude Code, Codex, Gemini CLI 또는 기본 터미널에서 수정 없이 작동합니다. 파일을 읽고 셸 명령을 실행할 수 있는 에이전트라면 필요한 모든 것을 갖추고 있습니다. 에이전트가 SKILL.md 대신 AGENTS.md를 읽는 경우, 두 파일 모두 존재하며 동일한 내용을 가리킵니다.

vLEI 샌드박스