Source Map
This map describes the lapee source tree
on PermaGit as it matters for launch docs, release engineering, and operator
behavior.
Top Level
| Path | Role |
|---|---|
README.md | Operator source of truth: quick start, build, verify, Secure Boot, security model, troubleshooting, repo layout. |
AGENTS.md | Public product guide for assistants learning LapEE from the docs site. |
Makefile | Public release surface: image build/write, signing keys, WiFi credentials, operator config injection, QEMU tests, HyperBEAM fetch. |
docker/Dockerfile | Host build image with Buildroot dependencies, EFI tooling, Rust, and cross-build helpers. |
.gitignore | Keeps build output, generated images, keys, WiFi credentials, and local HyperBEAM worktrees out of git. |
Buildroot External Tree
| Path | Role |
|---|---|
buildroot-external/configs/lapee_defconfig | x86_64 Buildroot config: Linux, Erlang, OpenSSL, tpm2-tss, networking, firmware, reproducible-build settings, HyperBEAM package. |
buildroot-external/configs/lapee-sb-provisioner.extra | Extra config for Secure Boot provisioner images. |
buildroot-external/board/lapee/rootfs-overlay/init | PID 1. Reads ESP inputs once, enforces memory-encryption gate, starts splash, configures network, detaches boot USB, deauthorizes USB, starts HyperBEAM. |
buildroot-external/board/lapee/rootfs-overlay/etc/lapee/lapee.json | Enforced HyperBEAM config. Registers LapEE devices and the startup boot-attestation hook. |
buildroot-external/board/lapee/rootfs-overlay/usr/libexec/lapee-dhcp-hook | DHCP hook. First interface with a gateway becomes the primary node URL source. |
buildroot-external/board/lapee/files/lapee_splash.erl | Animated console splash and status monitor. Shows the live URL and QR when HyperBEAM is ready. |
buildroot-external/board/lapee/files/lapee-sb-provisioner.c | EFI variable provisioner used by the Secure Boot enrollment image. |
buildroot-external/board/lapee/linux-*.config | Kernel fragments for production, debug, and Secure Boot provisioner builds. |
buildroot-external/package/hyperbeam/hyperbeam.mk | Buildroot package for pinned HyperBEAM plus the LapEE overlay, Erlang release, C/Rust NIF cross-compile, and runtime slimming. |
buildroot-external/package/hyperbeam/Config.in | Buildroot package declaration. |
buildroot-external/external.desc, external.mk, Config.in | Buildroot external-tree wiring. |
buildroot-external/post-build.sh | Stages splash beam, firmware, regulatory data, and rootfs sanity checks. |
Scripts
| Path | Role |
|---|---|
scripts/build-buildroot.sh | Downloads pinned Buildroot and source packages, stages overlays, runs Buildroot inside Docker, and exports kernel/initramfs artifacts. |
scripts/build-usb-image.sh | Builds the GPT/FAT32 USB image with UKI, marker, README, optional WiFi/config files, and optional Secure Boot enrollment bundle. |
scripts/sb-setup.sh | Generates Secure Boot PK/KEK/db material, signs UKIs, and prepares enrollment files. |
scripts/gather-wifi-creds.sh | Interactively writes strict two-line wifi.conf without printing the PSK. |
scripts/interpret-local-capture.sh | Fetches or reads evidence, runs ~tpm-interpret@1.0, and writes claim, interpretation, text output, input preview, and dashboard. |
scripts/fetch-ek-root-cas.sh | Refreshes the measured TPM EK root/intermediate CA corpus from Keylime plus explicit AMD, Infineon, Nuvoton, and Intel anchors. |
scripts/stage-hyperbeam-overlay.sh | Copies LapEE devices/native code/data into a generated HyperBEAM checkout and inserts the lapee rebar profile. |
scripts/boot-usb-image.sh | Boots a runtime image under QEMU+OVMF+swtpm and fetches live evidence through forwarded port 18734. |
scripts/qemu-green-zone-cluster.sh | Multi-node green-zone acceptance harness. |
scripts/qemu-green-zone-requests.py | Generates request bodies for the green-zone QEMU harness. |
scripts/qemu-operator-config-green-zone.sh | Proves config.json reaches ~meta@1.0/info, boot attestation, verifier replay, and green-zone template matching. |
scripts/render-splash-previews.sh | Renders local text/ANSI previews for splash layouts. |
scripts/capture-splash-qemu.sh | Captures framebuffer screenshots from QEMU splash variants. |
HyperBEAM Overlay
| Path | Role |
|---|---|
hyperbeam-overlay/rebar.lapee.fragment | Rebar profile fragment staged into HyperBEAM. |
hyperbeam-overlay/src/dev_tpm2.erl | Main TPM device: PCR read/extend, EK/AK, quote, boot attestation, credential activation, peer verification, and verifier entrypoints. |
hyperbeam-overlay/src/dev_tpm_interpret.erl | Evidence interpreter: checks, claims, summaries, policy verdicts, peer status, event decoding. |
hyperbeam-overlay/src/dev_tpm_tcg.erl | TCG event-log parser and replay support. |
hyperbeam-overlay/src/dev_system.erl | Redacted system evidence device. |
hyperbeam-overlay/src/dev_green_zone.erl | Evidence-gated shared identity admission device. |
hyperbeam-overlay/src/hb_db_tpm.erl | TPM interpretation data access. |
hyperbeam-overlay/src/lapee_aia.erl | HTTPS-only AIA intermediate fetcher for EK chains. |
hyperbeam-overlay/src/lapee_peer_http.erl | Peer HTTP helper that preserves full HyperBEAM response messages. |
hyperbeam-overlay/src/lapee_tpm_nif.erl | Erlang wrapper for native libtss2 ESYS TPM operations. |
hyperbeam-overlay/native/lapee_tpm_nif/* | C NIF implementation and helpers for TPM startup, PCR operations, EK/AK creation, quote, NV reads, MakeCredential, and ActivateCredential. |
hyperbeam-overlay/priv/tpm-interpret/* | Measured interpretation corpus: TPM vendor data, root CAs, PCR profiles, UKI measurements, firmware metadata, IMA policies, and fixtures. |
Secondary Verifier
| Path | Role |
|---|---|
secondary-external-verifier/README.md | Minimal external verifier usage and check list. |
secondary-external-verifier/verifier_hb.py | Python verifier for captured boot-attestation envelopes. Checks EK chain, quote, AK policy, runtime PCR 15 replay, and node-message commitment. |
Paper
| Path | Role |
|---|---|
paper/* | LaTeX, bibliography, figures, and generated PDF for the LapEE paper. It is background material, not runtime code. |