jmrp.io / kleidos

0

[READ-ONLY] Mirror of https://github.com/jmrplens/kleidos. Kleidos — Hardware BLE password manager for ESP32-S3 (M5StickC Plus2, StickS3, M5Stack Gray, T-Deck, Cardputer) jmrplens.github.io/kleidos/

0

kleidos / docs / testing /

at main 6 files

José M. Requena Plens Add the WiFi-station store and NTP clock-sync backend 5d ago

Add the WiFi-station store and NTP clock-sync backend From Settings (vault unlocked) the device can join a saved WiFi network as a station, sync the clock via one-shot SNTP against trusted public NTP servers, and always disconnect. Servers are LITERAL IPv4 only — never a hostname, never DNS (esp_sntp is fed parsed addresses; a strict dotted-quad validator gates every entry). Defaults are Cloudflare (162.159.200.1, 162.159.200.123), Google (216.239.35.0) and NIST (132.163.97.1), tried in order; the user can persist an override list of up to four IPs so dead defaults never require a firmware update. Saved networks (SSID+PSK, max 8) and the NTP server list live in a new wifi.bin vault module using the standard envelope (AES-256-CBC + HMAC-SHA256, encrypt-then-MAC, verify-before-decrypt, type-bound), only readable with the vault unlocked, staged through the crash-safe rekey, and crypto-erased by wipeAll. PSKs are zeroized after use and never logged or echoed. The sync engine runs on a Core-0 worker: BLE off, join the strongest saved network, query servers in order, sanity-clamp the epoch and never step backward past an armed lockout, commit via the rtc facade with a new display-only src=ntp tag — clock TRUST is never elevated (NTP is unauthenticated; the forward-jump lockout fail-closed model is the spoofing defense) — then a RAII station guard tears WiFi down and restores BLE on every exit path. The station facade stays a generic transport for future consumers (on-device OTA). Debug console gains WIFISCAN / WIFIADD / WIFILIST / WIFIDEL, NTPSYNC (GPSSYNC-style blocking flow with machine-checkable teardown acks) and NTPSERVERS? / NTPSERVERSET / NTPSERVERCLEAR — all DEBUG_SERIAL_BUTTONS gated. HIL-verified end to end on the StickS3: real sync against the default servers, user-list precedence across reboot, TEST-NET failure paths, trust unchanged, BLE restored, store left clean. Claude-Session: https://claude.ai/code/session_01SV58JXhfxhhc9DC6vdjBo4

5 days ago

ble-hid-hardware-qa.md

Harden BLE bond lifecycle and land full on-device QA coverage Defensive BLE audit of src/ble/ (audit dossier: docs/security/audit-ble.md). The stack was sound; this closes the one actionable finding plus the QA gaps. BLE-L1 (the finding): BLE bonds survived a vault wipe / factory reset — the NimBLE keystore (nimble_bond NVS), the kleidos_blnames name blob, and its RTC mirror all live in NVS, which wipeAll() never touched, so a previous owner's bonded hosts and the device IRK persisted across a factory reset. Add BondStore::factoryReset() (erases all three backing stores, radio OFF) exposed via Facade::factoryResetBonds() and wired into every wipe path (pin_state brute-force wipe, settings wipe, boot recovery, debug WIPEVAULT/lockout). Clearing the RTC mirror is essential — reconcile() would otherwise resurrect the bonds after the post-wipe reboot. Validated on-device. Native regression in test_bond_store / test_name_store. QA coverage: implement and validate the eight proposed BLE QA tests — nc-reject (QA-1), conn-param (QA-2), disconnect (QA-4), factory-reset regression (QA-5), adv-minimization (QA-7) on the mastodon Linux/BlueZ central; redaction (QA-6) + UTF-8 robustness (QA-8) in CI; and N4 eviction (QA-3) end-to-end on the DUT via the ESP32 Plus1 central. New mastodon scenarios (adv-scan, disconnect-mid-type, conn-param, evict, restore) in ble_attack.sh + ble_probe.py. Plus1 harness: unify the separate _blehost/_wifihost binaries into one command-switchable BLE+WiFi binary (m5stickc_plus1_host, MODE BLE|WIFI|NONE). Add an OWNADDR command that rotates the central's LE random-static identity (fills the DUT bond table for N4 eviction, no BlueZ). Fix two firmware bugs: the harness was mute without KLEIDOS_USB_SERIAL_CONSOLE (serial facade compiled to no-op stubs), and identity rotation broke discovery until OWNADDR/FORGET also clear the resolving list (ble_hs_resolv_list_clear_all). CVE maintenance: register CVE-2025-53470/53477 (NimBLE HCI, low-reachability) and record the advertising-report/Mesh/BlueDroid/BluFi CVEs as not-applicable; 2026 re-check found no new NimBLE CVEs. Plus readability + file:line doc-drift fixes across ble.md / cve-register.md. Gates: native 233/233, sticks3 + m5stickc_plus2 + m5stickc_plus1_host build clean, pio check no defects, clang-format/check_layout/check_variants/typos/ gitleaks/ruff/editorconfig all pass. Claude-Session: https://claude.ai/code/session_01MyjYtwfLCwUUfGVYuTQqSv

2 weeks ago

hal-smoke-qa.md

Refresh BLE HID and HAL smoke QA runbooks to the pytest system Replace all stale references to the legacy scripts/ble_host_pairing_test.py and scripts/hal_smoke_test.py orchestrators, /mnt/build absolute paths, and hardcoded /dev/ttyACM* device paths with the current pytest qa/ system: - hal-smoke-qa.md: 10 stale refs replaced with pytest tests/serial/ invocations - ble-hid-hardware-qa.md: 8 stale refs replaced with pytest tests/ble/ and inventory-based DUT/host selection; device roles updated (mastodon/plus1) - serial-debug-commands.md: 1 stale ble_host_pairing_test.py bullet merged into the existing qa/ note; scripts that still exist are unchanged video-qa-capture.md: verified accurate; no change required. Claude-Session: https://claude.ai/code/session_01Y7Cy1HetRp6TZAUAeekN8X

2 weeks ago

Document deferred Sphinx API-docs plan for qa/ Add "Future: API docs via Sphinx (not built)" appendix to docs/testing/qa-system.md. Records the intended Sphinx + autodoc + sphinx-autodoc-typehints setup (docs/qa/ source layout, requirements-docs.txt, no Napoleon since we use native RST field lists) so the deferral decision is captured without building the infrastructure yet. Claude-Session: https://claude.ai/code/session_01Y7Cy1HetRp6TZAUAeekN8X

2 weeks ago

serial-debug-commands.md

Add the WiFi-station store and NTP clock-sync backend From Settings (vault unlocked) the device can join a saved WiFi network as a station, sync the clock via one-shot SNTP against trusted public NTP servers, and always disconnect. Servers are LITERAL IPv4 only — never a hostname, never DNS (esp_sntp is fed parsed addresses; a strict dotted-quad validator gates every entry). Defaults are Cloudflare (162.159.200.1, 162.159.200.123), Google (216.239.35.0) and NIST (132.163.97.1), tried in order; the user can persist an override list of up to four IPs so dead defaults never require a firmware update. Saved networks (SSID+PSK, max 8) and the NTP server list live in a new wifi.bin vault module using the standard envelope (AES-256-CBC + HMAC-SHA256, encrypt-then-MAC, verify-before-decrypt, type-bound), only readable with the vault unlocked, staged through the crash-safe rekey, and crypto-erased by wipeAll. PSKs are zeroized after use and never logged or echoed. The sync engine runs on a Core-0 worker: BLE off, join the strongest saved network, query servers in order, sanity-clamp the epoch and never step backward past an armed lockout, commit via the rtc facade with a new display-only src=ntp tag — clock TRUST is never elevated (NTP is unauthenticated; the forward-jump lockout fail-closed model is the spoofing defense) — then a RAII station guard tears WiFi down and restores BLE on every exit path. The station facade stays a generic transport for future consumers (on-device OTA). Debug console gains WIFISCAN / WIFIADD / WIFILIST / WIFIDEL, NTPSYNC (GPSSYNC-style blocking flow with machine-checkable teardown acks) and NTPSERVERS? / NTPSERVERSET / NTPSERVERCLEAR — all DEBUG_SERIAL_BUTTONS gated. HIL-verified end to end on the StickS3: real sync against the default servers, user-list precedence across reboot, TEST-NET failure paths, trust unchanged, BLE restored, store left clean. Claude-Session: https://claude.ai/code/session_01SV58JXhfxhhc9DC6vdjBo4

5 days ago

video-qa-capture.md

Decommission migrated QA scripts, document future CI runner (Phase 6+7) Retire the loose QA scripts now fully reproduced by the qa/ pytest system, after integrating the two capabilities that were still missing (both validated on hardware): E4/BLERP bond-overwrite security (tests/ble/test_ble_security.py:: test_blerp_repair_confirm_e4) and the serial FSM soak (tests/serial/ test_fsm_flows.py::test_unlock_lock_soak, 15 cycles green). Deleted (superseded, all capability reproduced): serial_button_test, serial_fsm_test, serial_flow_test, ble_e3_nc_reject, ble_e4_repair_confirm, ble_fresh_pair_stress, admin_api_test, wifi_admin_test, video_qa, stress_test. Kept (unique value not reproduced in automated pytest): ble_host_pairing_test(.py /_sticks3) — the Plus1 BLE fallback, since host/plus1.py is still a stub (the plan defers the unified-MODE harness); hal_smoke_test.py (interactive physical-button / keyboard bring-up); serial_screenshot.py + capture_* (the design screenshot-preset workflow); resource_monitor_tui.py (live dev TUI). The on-server linux-harness (incl. run.py, which the host layer wraps) is unchanged. Docs: point QA_CHECKLIST, developer-guide, security/wifi, testing/README, serial-debug-commands, and video-qa-capture at the qa/ pytest equivalents; qa/ provenance comments drop the dead script paths. `rg` finds no reference to any deleted script. Phase 7 (self-hosted CI runner) is documented as an appendix in docs/testing/qa-system.md, not built. Gate: no-hardware suite green (32 passed); ruff + black clean; no dangling refs. Claude-Session: https://claude.ai/code/session_01Y7Cy1HetRp6TZAUAeekN8X

2 weeks ago

README.md

Kleidos Testing Documentation#

This directory contains repeatable QA runbooks for hardware-backed tests that need more context than a single command line.

QA system operator guide: the qa/ pytest system — the single entry-point for serial, BLE, WiFi, and video HIL tests (replaces the old loose scripts/ QA runners).
Serial debug command reference: every serial command exposed by *_debug builds (navigation, FSM, onboarding, vault, BLE, WiFi, resource/CPU telemetry, display/power persistence).
BLE HID hardware QA: two-device BLE security, HID typing, reconnect, timeout, and stress testing.
HAL smoke QA: on-device HAL/diagnostic smoke tests.
Live-video UI capture: record the device UI in motion over WiFi (VIDEO serial commands + the qa/ video test).

Future WiFi/AP/OTA QA runbooks should follow the same structure: device roles, build/flash steps, scenario descriptions, expected output, failure triage, and security or power rationale.