# 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