feat: add ESP32 embedded agent + namespace VRF reference docs + update android-agent submodule

- apps/device-agent-embedded/: ESP32 WireGuard agent (C, ESP-IDF, mbedTLS) - reference/namespace-vrf/: Linux namespace/VRF network isolation docs - apps/android-agent: VPN permission check, StartResult sealed class
2026-09-13 14:39:24 +07:00
parent 88fa60901e
commit e523398fa8
31 changed files with 6766 additions and 1 deletions
@@ -0,0 +1,126 @@
+# NexusGuard Embedded Agent
+
+ESP32-based WireGuard agent for IoT/edge devices. Connects to NexusGuard Server Core via HTTP provisioning + heartbeat, manages WireGuard tunnel via lwIP stack.
+
+## Overview
+
+This agent runs on ESP32 (LW840X and compatible) with FreeRTOS + ESP-IDF. It provides:
+
+- **Zero-Trust VPN Tunnel**: WireGuard over lwIP
+- **Auto-Provisioning**: HTTP-based key exchange with server
+- **Heartbeat Monitoring**: Periodic status reports + config sync
+- **NVS Config Persistence**: WireGuard keys stored in flash (never disk)
+- **Independent Build**: No dependency on main NexusGuard repo
+
+## Hardware Requirements
+
+| Component | Specification |
+|-----------|---------------|
+| MCU | ESP32 (Xtensa LX7) or ESP32-S3 |
+| RAM | ≥ 320KB SRAM |
+| Flash | ≥ 4MB |
+| WiFi | 802.11 b/g/n |
+| antenna | U.FL or PCB trace |
+
+## Quick Start
+
+### 1. Install ESP-IDF
+
+```bash
+# Follow official guide: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/get-started/
+# ESP-IDF v5.2+ required
+```
+
+### 2. Configure Server
+
+```bash
+# Set server URL, registration token, and WiFi credentials
+idf.py menuconfig
+# Navigate to: Component config → NexusGuard Agent
+```
+
+Or edit `sdkconfig.defaults` directly:
+
+```
+CONFIG_NEXUS_SERVER_URL="https://api-nexus.datadunia.com"
+CONFIG_NEXUS_REG_TOKEN="your-registration-token"
+CONFIG_NEXUS_SERVER_SALT="your-server-salt"
+CONFIG_NEXUS_WIFI_SSID="your-wifi-ssid"
+CONFIG_NEXUS_WIFI_PASSWORD="your-wifi-password"
+```
+
+### 3. Build & Flash
+
+```bash
+idf.py set-target esp32
+idf.py build
+idf.py -p /dev/ttyUSB0 flash monitor
+```
+
+## Server Configuration
+
+The agent requires the following server configuration:
+
+| Parameter | Description | Where to Find |
+|-----------|-------------|---------------|
+| Server URL | API endpoint | `https://api-nexus.datadunia.com` |
+| Registration Token | Single-use provisioning token | Server admin dashboard |
+| Server Salt | AES-256-GCM key derivation | Server `.env` file (`SERVER_SALT`) |
+
+### Provisioning Flow
+
+1. Create device in server dashboard
+2. Copy registration token
+3. Configure agent with token (menuconfig or NVS)
+4. Agent boots → connects WiFi → provisions → builds tunnel
+
+### Heartbeat
+
+Agent sends heartbeat every 30 seconds:
+
+```json
+POST /api/v1/heartbeat
+{
+  "device_id": "uuid",
+  "status": "connected",
+  "tunnel_up": true,
+  "last_handshake": "2026-06-26T09:00:00Z"
+}
+```
+
+Server responds with config sync (detects changes, triggers rebuild).
+
+## Project Structure
+
+```
+nexus-agent-embedded/
+├── main/
+│   ├── main.c              # Entry point
+│   ├── provision.c         # HTTP provisioning
+│   ├── heartbeat.c         # HTTP heartbeat loop
+│   ├── tunnel.c            # WireGuard via lwIP
+│   ├── crypto.c            # AES-256-GCM decrypt
+│   ├── config.c            # NVS config storage
+│   └── wifi.c              # WiFi management
+├── components/
+│   └── wireguard-esp32/    # WireGuard library
+├── docs/
+│   ├── DESIGN.md           # Technical design
+│   ├── API_COMPAT.md       # Server API compatibility
+│   └── HARDWARE.md         # Hardware reference
+├── CMakeLists.txt
+├── Kconfig                 # Menuconfig options
+├── sdkconfig.defaults
+├── AGENTS.md               # AI agent knowledge base
+└── README.md
+```
+
+## Documentation
+
+- [Technical Design](docs/DESIGN.md)
+- [API Compatibility](docs/API_COMPAT.md)
+- [Hardware Reference](docs/HARDWARE.md)
+
+## License
+
+Proprietary - NexusGuard