gr0m-chat: public project scaffold + gr0m-integrity overlay docs#3
Closed
MichaelAdamGroberman wants to merge 16 commits into
Closed
gr0m-chat: public project scaffold + gr0m-integrity overlay docs#3MichaelAdamGroberman wants to merge 16 commits into
MichaelAdamGroberman wants to merge 16 commits into
Conversation
Approved design for a multi-board (ESP32 + Pico W) WireGuard-to-Tailscale integration: reusable TailnetPeer library + private-sensor demo app, node-agnostic subnet-router gateway, security-first defaults.
12 bite-sized tasks: PlatformIO scaffold, TDD wg-quick parser, TailnetPeer state machine over a WgBackend interface, ESP32 + Pico W backends, two examples, node-agnostic gateway script, sensor demo app, docs, CI, and the repo-protection set (publish gated on user confirmation).
Add platformio.ini (native/esp32-s3/pico-w envs), library.json, library.properties, .gitignore, and MIT LICENSE to bootstrap the PlatformIO library structure for tailnet-mcu.
…ale tunnel Adds RadioManager (enforces WiFi/BT mutual exclusion), ServiceTransport abstraction (BLE NimBLE/BTstack + token-gated TCP), constant-time token gate; makes the WireGuard tunnel an opt-in WiFi-mode layer. BLE on both boards with Pico W BTstack as a spike that degrades to documented-stub.
Also fixes the native test env: standard test_build_src + -I src + source filter (the symlink:// lib_deps was breaking Unity auto-injection). 5/5 pass.
RadioHooks interface keeps the mode logic host-testable; FakeHooks asserts the two radios are never simultaneously on across all transitions. 5/5 pass.
…nsport token_gate is host-tested (5/5, constant-time compare). ServiceTransport and TcpServiceTransport are Arduino (compile-gated; verified on-board via examples).
Optional WireGuard tunnel: parse-then-start, poll handshake to UP, FAILED on bad config or backend failure. FakeBackend keeps it host-testable. 5/5 pass; full native suite now 20/20.
setup-subnet-router.sh runs on any existing Tailscale node (on-LAN or public); scoped /32 AllowedIPs, MASQUERADE to tailscale0, route advertisement. ACL JSON validated; bash -n clean (shellcheck enforced in CI).
- src/backends/backend_esp32.{h,cpp}: Esp32WgBackend wrapping WireGuard-ESP32
- src/transport/ble_service_transport.h: board-agnostic NUS BLE transport interface
- src/transport/ble/ble_nimble_esp32.cpp: NimBLE 2.x NUS impl (auth-gated RxCallback,
disconnect resets auth, advertising auto-restarts)
- examples/minimal_tunnel: WiFi + WireGuard tunnel + TCP reach-test sketch
- examples/mode_switch: RadioManager WiFi↔BT switching demo sketch
- app/tailnet-sensor-node: full demo app (ESP32-S3 + Pico W placeholder),
optional WG tunnel, temperatureRead() JSON sensor, mode-switch handler
- Switch WireGuard dep to felipedadison/WireGuard-ESP32@^0.2.0 (IDF5/arduino-esp32
3.x compat); ciniml@0.1.5 breaks on tcpip_adapter.h removal in IDF5
- Verified: esp32-s3 build SUCCESS (32.8% flash, 15.6% RAM)
… + 2C)
Task 5 — Pico W WireGuard backend (REAL):
Spike found jaszczurtd/arduino-wireguard-pico-w 0.1.8 on PlatformIO
registry — a direct port of WireGuard-ESP32 to RP2040 + lwIP. API is
identical (WireGuard::begin / end / is_initialized / peerUp).
PicoWWgBackend wraps it with the same WgBackend interface used by the
ESP32 backend; isUp() maps to peerUp() for handshake detection.
Task 2C — Pico W BTstack BLE transport (STUB, documented):
Spike found iot-gamer/pico-ble-notify (TX/notify) and raw BTstackLib.h.
Both rely on a single global gattWriteCallback() symbol the app must
define; a library-internal definition would silently collide with any
app-side callback. Stub logs the limitation and returns false.
v2 design (bleWriteHook / app-forwarded callback) recorded in stub header.
platformio.ini changes:
• pico-w env: adds jaszczurtd/arduino-wireguard-pico-w @ ^0.1.8
• pico-w env: lib_ignore = WireGuard-ESP32, NimBLE-Arduino to prevent PIO
from pulling ESP32-only libs when resolving the file:// local dependency
(root platformio.ini lists them for esp32-s3 and PIO resolves transitively)
Compile result:
pico-w SUCCESS RAM 27.4 % / Flash 17.5 %
native 20/20 tests PASSED (no regressions)
esp32-s3 Python 3.14 constraint pre-exists; not caused by this commit
Plain 'espressif32' resolves to the registry arduino-esp32 2.x, which breaks the felipedadison WG fork + NimBLE 2.x combo. Pinning to the exact pioarduino release that produced the clean build (63d263c) makes CI + contributor builds reproducible.
…po-protection README leads with the honest 'MCU runs WireGuard not Tailscale' framing and an accurate board table (Pico W BLE = experimental stub). Adds CI (native tests + board compile matrix + shellcheck), SECURITY/CONTRIBUTING/CoC/CODEOWNERS, and issue/PR templates. Gitignores the build-generated idf_component.yml.
…g-up checklist - architecture.md: spell out the contract — all radio bring-up must go through RadioManager and stop hooks must fully deinit (else the heap guarantee is defeated). Also corrects the ESP32 WG lib name (felipedadison fork, not ciniml). - docs/hardware-bringup.md (new): on-device checklist incl. a free-heap-across- switch step to confirm the radios never coexist and the stack is reclaimed. - README: link the hardware checklist from Build and test.
…lay docs Self-contained gr0m-chat/ project ready to lift into a standalone public repo: star-oriented README focused on what the integrity color coding does (plain = cleared, pink/red = flagged/unsupported, U+FFFD = unverifiable tokens), an integrity-overlay deep-dive, and MIT LICENSE. Implementation of the detection engine is intentionally undocumented; companies are directed to groberman.tech.
MichaelAdamGroberman
force-pushed
the
claude/gr0m-chat-project-setup-j5VEu
branch
from
2d28c4c to
d36d20c
Compare
|
| GitGuardian id | GitGuardian status | Secret | Commit | Filename | |
|---|---|---|---|---|---|
| 33139516 | Triggered | Generic High Entropy Secret | 04a585d | test/test_wgconfig/test_wgconfig.cpp | View secret |
🛠 Guidelines to remediate hardcoded secrets
- Understand the implications of revoking this secret by investigating where it is used in your code.
- Replace and store your secret safely. Learn here the best practices.
- Revoke and rotate this secret.
- If possible, rewrite git history. Rewriting git history is not a trivial act. You might completely break other contributing developers' workflow and you risk accidentally deleting legitimate data.
To avoid such incidents in the future consider
- following these best practices for managing and storing secrets including API keys and other credentials
- install secret detection on pre-commit to catch secret before it leaves your machine and ease remediation.
🦉 GitGuardian detects secrets in your source code to help developers and security teams secure the modern development process. You are seeing this because you or someone else with access to this repository has authorized GitGuardian to scan your pull request.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What this adds
A self-contained
gr0m-chat/project, ready to lift into a standalone public repo:gr0m-chat/README.md— star-oriented public README. Centers on what the gr0m-integrity color coding does rather than how it's built:�markers = unverifiable tokensgr0m-chat/docs/integrity-overlay.md— long-form guide to reading and acting on the overlay.gr0m-chat/LICENSE— MIT (the detection engine is explicitly excluded / unpublished).Decisions baked in
Notes
tailnet-mcu). The project is structured as a drop-ingr0m-chat/directory so it can be moved into its own repo in one step once created with appropriate permissions.https://claude.ai/code/session_01YQZNGJEL3hjVGccWVYBDUS
Generated by Claude Code