| name | keystone-zig-architecture |
| description | Guides clean-room Keystone TEE implementation in native Zig for clarigggz. Use when working on keystone-zig architecture, clarigggz integration, threat model, boot chain, or deciding what to port from upstream Keystone. |
keystone-zig Architecture
Core mandate
Implement Keystone design patterns in Zig. Never import upstream C/C++ Keystone (OpenSBI port, Eyrie, C++ SDK).
Three rings
| Mode | Owner | Responsibility |
|---|
| M | sm/ | PMP arbiter, enclave table, SBI trap handler |
| S | clarigggz kernel + enclaves | Request enclaves via ecall |
| U | Adapters | Untrusted; no direct SM access |
Integration with clarigggz
- clarigggz Core Broker replaces
kernel/main.zig as S-mode payload.
- Secure tasks (camera crypto, wallet) run as S-mode enclaves in PMP bubbles.
- No Eyrie — kernel calls SM directly via extension
0x08424b45.
Phased roadmap
- Boot + static PMP + SBI stubs (current)
- Full context switch (satp, PMP swap, trap frame)
- Attestation + sealing
- clarigggz adapter enclaves
Key files
docs/architecture.md — full system map
docs/decisions/001-m-mode-first.md — why M-mode boots first
AGENTS.md — agent hard rules
Anti-patterns
- Dropping OpenSBI/Keystone submodules into this repo
- Letting S-mode code write PMP CSRs
- Adding libc or C++ dependencies
Additional resources
- Upstream spec reference (read-only): sibling
keystone/sm/spec/v1.0.md
- clarigggz OS:
clarigggzOS/ hexagonal microkernel