diff --git a/luci-app-network-modes/CODEX-v0.3.5.md b/luci-app-network-modes/CODEX-v0.3.5.md new file mode 100644 index 00000000..c353c0bd --- /dev/null +++ b/luci-app-network-modes/CODEX-v0.3.5.md @@ -0,0 +1,1176 @@ +# Network Modes v0.3.5 Development Codex + +**Target Version:** 0.3.5 +**Current Version:** 0.3.4 +**Release Date:** 2025-01-15 +**Priority:** High - Production Feature Completion +**Maintainer:** SecuBox Development Team + +--- + +## ๐ŸŽฏ Mission Statement + +Transform `luci-app-network-modes` from a **50% placeholder UI** into a **production-ready network mode switching system** by implementing real backend functionality for WireGuard relay, web proxy, HTTPS reverse proxy, advanced WiFi features, and packet capture. + +--- + +## ๐Ÿ“Š Current State Analysis (v0.3.4) + +### โœ… What's Production-Ready (50-60%) + +**Core Framework:** +- โœ… Mode switching with 2-minute auto-rollback protection +- โœ… UCI-based configuration persistence (26 options) +- โœ… Automatic backup/restore (`/etc/network-modes-backup/`) +- โœ… RPCD backend with 18 methods (1190 lines) +- โœ… 7 JavaScript views with real RPC wiring +- โœ… Status dashboard with interface/service monitoring + +**Basic Network Modes:** +- โœ… Router mode: WAN/LAN, NAT, DHCP server, firewall zones +- โœ… Access Point mode: WiFi channel, HT mode, TX power, bridge DHCP +- โœ… Sniffer mode: Bridge config, promiscuous mode, Netifyd toggle +- โœ… Relay mode: Basic STA+AP relay, relayd configuration + +### โŒ What's Placeholder (40-50%) + +**Router Mode Gaps:** +- โŒ Web proxy (Squid/TinyProxy/Privoxy) - UI only, no config generation +- โŒ HTTPS reverse proxy (Nginx/HAProxy) - no config files created +- โŒ Let's Encrypt automation - no ACME integration +- โŒ DNS over HTTPS - no DoH proxy setup +- โŒ Virtual host deployment - stored in UCI but not applied + +**Access Point Mode Gaps:** +- โŒ 802.11r Fast Roaming - flag set, no MDID/FT config +- โŒ 802.11k RRM - no neighbor reports generated +- โŒ 802.11v BSS Transition - no WNM/TFS rules +- โŒ Band steering - no actual steering algorithm +- โŒ Airtime fairness - flag only, no hostapd config + +**Relay Mode Gaps:** +- โŒ WireGuard key generation - no wg genkey integration +- โŒ WireGuard peer config - UI shows but backend doesn't deploy +- โŒ MTU/MSS clamping - stored but no iptables rules created +- โŒ TCP BBR congestion control - mentioned but not implemented +- โŒ WireGuard interface up/down control + +**Sniffer Mode Gaps:** +- โŒ PCAP capture to file - no tcpdump integration +- โŒ Capture filter validation - stored but not applied +- โŒ SPAN port config - not implemented +- โŒ Wireshark export - mentioned only +- โŒ Long-term packet storage management + +--- + +## ๐Ÿš€ Version 0.3.5 Goals + +### Primary Objectives + +1. **Implement WireGuard Relay Features** (Critical - 30% of v0.3.5) + - Generate WireGuard private/public keys + - Deploy peer configurations to `/etc/config/network` + - Create iptables MSS/MTU clamping rules + - Enable TCP BBR congestion control + +2. **Implement Web Proxy Features** (High - 25% of v0.3.5) + - Generate Squid configuration files + - Implement transparent proxy iptables rules + - Add TinyProxy/Privoxy as alternatives + - Create DNS over HTTPS proxy config + +3. **Implement HTTPS Reverse Proxy** (High - 20% of v0.3.5) + - Generate Nginx/HAProxy vhost configs + - Integrate ACME (Let's Encrypt) automation + - Implement certificate renewal cron jobs + - Add SSL certificate validation + +4. **Implement Advanced WiFi Features** (Medium - 15% of v0.3.5) + - Generate 802.11r MDID and FT keys + - Create 802.11k neighbor reports + - Implement basic band steering + - Add hostapd config for 802.11v + +5. **Implement Packet Capture Features** (Medium - 10% of v0.3.5) + - Integrate tcpdump for PCAP capture + - Add capture filter validation + - Implement PCAP rotation logic + - Create passive monitor mode config + +### Success Criteria + +- [ ] All 18 RPCD methods have real backend implementations (not just UCI storage) +- [ ] Generated configs are validated before deployment +- [ ] Services are automatically started/stopped/reloaded +- [ ] Rollback mechanism restores service configs (not just UCI) +- [ ] Integration tests pass for all 4 network modes +- [ ] Documentation updated with real command examples +- [ ] No placeholder comments remain in RPCD backend + +--- + +## ๐Ÿ”ง Technical Implementation Plan + +### Phase 1: WireGuard Relay Features (Week 1-2) + +#### Task 1.1: WireGuard Key Management +**File:** `root/usr/libexec/rpcd/luci.network-modes` +**Method:** `generate_wireguard_keys()` (new) + +**Implementation:** +```bash +generate_wireguard_keys() { + # Check if wireguard-tools is installed + if ! command -v wg >/dev/null 2>&1; then + printf '{"error": "wireguard-tools not installed", "success": false}\n' + return 1 + fi + + # Generate private key + local privkey=$(wg genkey) + local pubkey=$(echo "$privkey" | wg pubkey) + + # Store in UCI (encrypted private key) + uci set network-modes.relay.wg_private_key="$privkey" + uci set network-modes.relay.wg_public_key="$pubkey" + uci commit network-modes + + printf '{"private_key": "%s", "public_key": "%s", "success": true}\n' \ + "$privkey" "$pubkey" +} +``` + +**Dependencies:** +- `wireguard-tools` package +- `/etc/config/network-modes` relay section + +**Validation:** +- Keys are 44 characters base64 +- Public key derives from private key +- UCI storage is persistent + +--- + +#### Task 1.2: WireGuard Interface Deployment +**File:** `root/usr/libexec/rpcd/luci.network-modes` +**Method:** `apply_wireguard_config()` (new) + +**Implementation:** +```bash +apply_wireguard_config() { + local wg_enabled=$(uci -q get network-modes.relay.wireguard_enabled || echo "0") + [ "$wg_enabled" = "1" ] || return 0 + + local privkey=$(uci -q get network-modes.relay.wg_private_key) + local peer_pubkey=$(uci -q get network-modes.relay.wg_peer_pubkey) + local peer_endpoint=$(uci -q get network-modes.relay.wg_peer_endpoint) + local wg_port=$(uci -q get network-modes.relay.wg_port || echo "51820") + local wg_ip=$(uci -q get network-modes.relay.wg_ip || echo "10.200.200.2/24") + + # Create WireGuard interface in /etc/config/network + uci set network.wg0=interface + uci set network.wg0.proto='wireguard' + uci set network.wg0.private_key="$privkey" + uci set network.wg0.listen_port="$wg_port" + uci add_list network.wg0.addresses="$wg_ip" + + # Add peer + uci set network.wg0_peer=wireguard_wg0 + uci set network.wg0_peer.public_key="$peer_pubkey" + uci set network.wg0_peer.endpoint_host="$peer_endpoint" + uci set network.wg0_peer.endpoint_port="$wg_port" + uci set network.wg0_peer.persistent_keepalive='25' + uci add_list network.wg0_peer.allowed_ips='0.0.0.0/0' + + uci commit network + /etc/init.d/network reload +} +``` + +**Config Example:** +```uci +config interface 'wg0' + option proto 'wireguard' + option private_key 'AAAA...ZZZZ=' + option listen_port '51820' + list addresses '10.200.200.2/24' + +config wireguard_wg0 + option public_key 'BBBB...YYYY=' + option endpoint_host 'vpn.example.com' + option endpoint_port '51820' + option persistent_keepalive '25' + list allowed_ips '0.0.0.0/0' +``` + +--- + +#### Task 1.3: MTU/MSS Clamping Rules +**File:** `root/usr/libexec/rpcd/luci.network-modes` +**Method:** `apply_mtu_clamping()` (new) + +**Implementation:** +```bash +apply_mtu_clamping() { + local mtu_optimize=$(uci -q get network-modes.relay.mtu_optimize || echo "0") + [ "$mtu_optimize" = "1" ] || return 0 + + local wg_mtu=$(uci -q get network-modes.relay.wg_mtu || echo "1420") + local mss_value=$((wg_mtu - 40)) # MTU - TCP/IP headers + + # Add MSS clamping to firewall + uci set firewall.mss_clamping=rule + uci set firewall.mss_clamping.name='WireGuard MSS Clamping' + uci set firewall.mss_clamping.src='lan' + uci set firewall.mss_clamping.dest='wan' + uci set firewall.mss_clamping.proto='tcp' + uci set firewall.mss_clamping.tcp_flags='SYN' + uci set firewall.mss_clamping.target='TCPMSS' + uci set firewall.mss_clamping.set_mss="$mss_value" + + uci commit firewall + /etc/init.d/firewall reload +} +``` + +**iptables Rule Generated:** +```bash +iptables -t mangle -A FORWARD -p tcp --tcp-flags SYN,RST SYN -j TCPMSS --set-mss 1380 +``` + +--- + +#### Task 1.4: TCP BBR Congestion Control +**File:** `root/usr/libexec/rpcd/luci.network-modes` +**Method:** `enable_tcp_bbr()` (new) + +**Implementation:** +```bash +enable_tcp_bbr() { + local tcp_optimize=$(uci -q get network-modes.relay.tcp_optimize || echo "0") + [ "$tcp_optimize" = "1" ] || return 0 + + # Check kernel support for BBR + if ! modprobe tcp_bbr 2>/dev/null; then + printf '{"error": "BBR not supported by kernel", "success": false}\n' + return 1 + fi + + # Enable BBR in sysctl + cat > /etc/sysctl.d/90-tcp-bbr.conf < /etc/squid/squid.conf </dev/null || true + + # Restart Squid + /etc/init.d/squid restart + + printf '{"success": true, "proxy": "squid", "port": %d}\n' "$proxy_port" +} +``` + +**Dependencies:** +- `squid` package +- `/var/spool/squid` directory (cache) + +--- + +#### Task 2.2: Transparent Proxy iptables Rules +**File:** `root/usr/libexec/rpcd/luci.network-modes` +**Method:** `apply_transparent_proxy_rules()` (new) + +**Implementation:** +```bash +apply_transparent_proxy_rules() { + local proxy_type=$(uci -q get network-modes.router.web_proxy || echo "none") + [ "$proxy_type" != "none" ] || return 0 + + local proxy_port=$(uci -q get network-modes.router.proxy_port || echo "3128") + + # Add redirect rule to firewall + uci set firewall.proxy_redirect=redirect + uci set firewall.proxy_redirect.name='Transparent Web Proxy' + uci set firewall.proxy_redirect.src='lan' + uci set firewall.proxy_redirect.proto='tcp' + uci set firewall.proxy_redirect.src_dport='80' + uci set firewall.proxy_redirect.dest_port="$proxy_port" + uci set firewall.proxy_redirect.target='DNAT' + + uci commit firewall + /etc/init.d/firewall reload +} +``` + +**Generated Rule:** +```bash +iptables -t nat -A PREROUTING -i br-lan -p tcp --dport 80 -j REDIRECT --to-ports 3128 +``` + +--- + +#### Task 2.3: DNS over HTTPS (DoH) Proxy +**File:** `root/usr/libexec/rpcd/luci.network-modes` +**Method:** `configure_doh_proxy()` (new) + +**Implementation:** +```bash +configure_doh_proxy() { + local doh_enabled=$(uci -q get network-modes.router.doh_enabled || echo "0") + [ "$doh_enabled" = "1" ] || return 0 + + local doh_provider=$(uci -q get network-modes.router.doh_provider || echo "cloudflare") + + case "$doh_provider" in + cloudflare) + local doh_url="https://1.1.1.1/dns-query" + ;; + google) + local doh_url="https://dns.google/dns-query" + ;; + quad9) + local doh_url="https://dns.quad9.net/dns-query" + ;; + *) + local doh_url="https://1.1.1.1/dns-query" + ;; + esac + + # Configure dnsmasq to use DNS over HTTPS + uci set dhcp.@dnsmasq[0].noresolv='1' + uci add_list dhcp.@dnsmasq[0].server="127.0.0.1#5053" + uci commit dhcp + + # Configure https_dns_proxy + uci set https-dns-proxy.dns.bootstrap_dns='1.1.1.1,1.0.0.1' + uci set https-dns-proxy.dns.listen_addr='127.0.0.1' + uci set https-dns-proxy.dns.listen_port='5053' + uci set https-dns-proxy.dns.url_prefix="$doh_url" + uci commit https-dns-proxy + + /etc/init.d/https-dns-proxy restart + /etc/init.d/dnsmasq restart + + printf '{"success": true, "doh_provider": "%s"}\n' "$doh_provider" +} +``` + +**Dependencies:** +- `https-dns-proxy` package +- dnsmasq with DoH support + +--- + +### Phase 3: HTTPS Reverse Proxy (Week 5-6) + +#### Task 3.1: Nginx Virtual Host Generator +**File:** `root/usr/libexec/rpcd/luci.network-modes` +**Method:** `deploy_nginx_vhosts()` (new) + +**Implementation:** +```bash +deploy_nginx_vhosts() { + local https_frontend=$(uci -q get network-modes.router.https_frontend || echo "0") + [ "$https_frontend" = "1" ] || return 0 + + # Get list of virtual hosts from UCI + local vhost_count=0 + + # Clear existing vhost configs + rm -f /etc/nginx/conf.d/vhost-*.conf + + # Iterate through virtual hosts stored in UCI + config_load network-modes + config_cb() { + local type="$1" + local name="$2" + [ "$type" = "vhost" ] || return 0 + + local domain backend_ip backend_port ssl_enabled + config_get domain "$name" domain + config_get backend_ip "$name" backend_ip + config_get backend_port "$name" backend_port "80" + config_get ssl_enabled "$name" ssl "0" + + [ -n "$domain" ] || return 0 + + # Generate Nginx vhost config + cat > /etc/nginx/conf.d/vhost-${name}.conf </dev/null || echo "0") + local now_epoch=$(date +%s) + local days_left=$(( (expiry_epoch - now_epoch) / 86400 )) + + if [ "$days_left" -lt 0 ]; then + printf '{"valid": false, "expired": true, "days_left": %d}\n' "$days_left" + return 1 + fi + + # Check certificate chain + local issuer=$(openssl x509 -issuer -noout -in "$cert_file" | grep -o 'Let.*Encrypt') + + printf '{"valid": true, "domain": "%s", "days_left": %d, "issuer": "%s"}\n' \ + "$domain" "$days_left" "$issuer" +} +``` + +--- + +### Phase 4: Advanced WiFi Features (Week 7-8) + +#### Task 4.1: 802.11r Fast Roaming +**File:** `root/usr/libexec/rpcd/luci.network-modes` +**Method:** `configure_80211r()` (new) + +**Implementation:** +```bash +configure_80211r() { + local ft_enabled=$(uci -q get network-modes.accesspoint.ieee80211r || echo "0") + [ "$ft_enabled" = "1" ] || return 0 + + local ssid=$(uci -q get wireless.@wifi-iface[0].ssid) + local mobility_domain=$(echo -n "$ssid" | md5sum | cut -c1-4) + + # Configure hostapd for 802.11r + uci set wireless.@wifi-iface[0].ieee80211r='1' + uci set wireless.@wifi-iface[0].mobility_domain="$mobility_domain" + uci set wireless.@wifi-iface[0].ft_over_ds='1' + uci set wireless.@wifi-iface[0].ft_psk_generate_local='1' + uci set wireless.@wifi-iface[0].reassociation_deadline='1000' + + uci commit wireless + wifi reload + + printf '{"success": true, "mobility_domain": "%s"}\n' "$mobility_domain" +} +``` + +**hostapd Config Generated:** +``` +mobility_domain=a1b2 +ft_over_ds=1 +ft_psk_generate_local=1 +reassociation_deadline=1000 +``` + +--- + +#### Task 4.2: 802.11k Neighbor Reports +**File:** `root/usr/libexec/rpcd/luci.network-modes` +**Method:** `configure_80211k()` (new) + +**Implementation:** +```bash +configure_80211k() { + local rrm_enabled=$(uci -q get network-modes.accesspoint.ieee80211k || echo "0") + [ "$rrm_enabled" = "1" ] || return 0 + + # Enable RRM in hostapd + uci set wireless.@wifi-iface[0].ieee80211k='1' + uci set wireless.@wifi-iface[0].rrm_neighbor_report='1' + uci set wireless.@wifi-iface[0].rrm_beacon_report='1' + + uci commit wireless + wifi reload + + printf '{"success": true, "rrm_enabled": true}\n' +} +``` + +**hostapd Config:** +``` +rrm_neighbor_report=1 +rrm_beacon_report=1 +``` + +--- + +#### Task 4.3: Band Steering Algorithm +**File:** `root/usr/libexec/rpcd/luci.network-modes` +**Method:** `enable_band_steering()` (new) + +**Implementation:** +```bash +enable_band_steering() { + local band_steering=$(uci -q get network-modes.accesspoint.band_steering || echo "0") + [ "$band_steering" = "1" ] || return 0 + + # Check if both 2.4GHz and 5GHz radios exist + local radio_2g=$(uci show wireless | grep "radio.*band='2g'" | cut -d. -f2 | cut -d= -f1 | head -n1) + local radio_5g=$(uci show wireless | grep "radio.*band='5g'" | cut -d. -f2 | cut -d= -f1 | head -n1) + + if [ -z "$radio_2g" ] || [ -z "$radio_5g" ]; then + printf '{"success": false, "error": "Dual-band radios required"}\n' + return 1 + fi + + # Enable hostapd band steering (requires wpa_supplicant) + uci set wireless.@wifi-iface[0].bss_load_update_period='60' + uci set wireless.@wifi-iface[0].chan_util_avg_period='600' + uci set wireless.@wifi-iface[0].disassoc_low_ack='1' + + uci commit wireless + wifi reload + + printf '{"success": true, "band_steering": "enabled"}\n' +} +``` + +--- + +### Phase 5: Packet Capture Features (Week 9) + +#### Task 5.1: tcpdump PCAP Capture +**File:** `root/usr/libexec/rpcd/luci.network-modes` +**Method:** `start_packet_capture()` (new) + +**Implementation:** +```bash +start_packet_capture() { + local pcap_enabled=$(uci -q get network-modes.sniffer.pcap_capture || echo "0") + [ "$pcap_enabled" = "1" ] || return 0 + + local capture_filter=$(uci -q get network-modes.sniffer.capture_filter || echo "") + local capture_interface=$(uci -q get network-modes.sniffer.capture_interface || echo "br-lan") + local max_size=$(uci -q get network-modes.sniffer.pcap_max_size || echo "100") + local rotate_count=$(uci -q get network-modes.sniffer.pcap_rotate || echo "10") + + # Create capture directory + mkdir -p /var/log/pcap + + # Kill existing tcpdump + killall tcpdump 2>/dev/null + + # Start tcpdump with rotation + tcpdump -i "$capture_interface" \ + -w /var/log/pcap/capture.pcap \ + -C "$max_size" \ + -W "$rotate_count" \ + ${capture_filter:+-s 0 $capture_filter} \ + >/dev/null 2>&1 & + + local tcpdump_pid=$! + echo "$tcpdump_pid" > /var/run/tcpdump.pid + + printf '{"success": true, "pid": %d, "interface": "%s"}\n' \ + "$tcpdump_pid" "$capture_interface" +} +``` + +**tcpdump Command Example:** +```bash +tcpdump -i br-lan -w /var/log/pcap/capture.pcap -C 100 -W 10 -s 0 'port 80 or port 443' +``` + +--- + +#### Task 5.2: Capture Filter Validation +**File:** `root/usr/libexec/rpcd/luci.network-modes` +**Method:** `validate_pcap_filter()` (new) + +**Implementation:** +```bash +validate_pcap_filter() { + local filter="$1" + [ -n "$filter" ] || { + printf '{"valid": true, "filter": "all"}\n' + return 0 + } + + # Test filter syntax with tcpdump + if tcpdump -i any -d "$filter" >/dev/null 2>&1; then + printf '{"valid": true, "filter": "%s"}\n' "$filter" + return 0 + else + printf '{"valid": false, "error": "Invalid BPF syntax"}\n' + return 1 + fi +} +``` + +**Valid Filter Examples:** +- `port 80 or port 443` - HTTP/HTTPS traffic +- `tcp and not port 22` - All TCP except SSH +- `host 192.168.1.100` - Specific host +- `net 10.0.0.0/8` - Network range + +--- + +#### Task 5.3: PCAP Rotation Management +**File:** `root/usr/libexec/rpcd/luci.network-modes` +**Method:** `cleanup_old_pcaps()` (new) + +**Implementation:** +```bash +cleanup_old_pcaps() { + local max_age=$(uci -q get network-modes.sniffer.pcap_retention_days || echo "7") + local pcap_dir="/var/log/pcap" + + # Find and delete old PCAP files + local deleted_count=0 + find "$pcap_dir" -name "*.pcap*" -mtime +${max_age} -type f | while read -r pcap_file; do + rm -f "$pcap_file" + deleted_count=$((deleted_count + 1)) + done + + # Calculate total size + local total_size=$(du -sm "$pcap_dir" 2>/dev/null | cut -f1 || echo "0") + + printf '{"success": true, "deleted": %d, "total_size_mb": %d}\n' \ + "$deleted_count" "$total_size" +} +``` + +**Cron Job for Auto-Cleanup:** +```bash +# Add to /etc/crontabs/root +0 2 * * * /usr/libexec/rpcd/luci.network-modes call cleanup_old_pcaps +``` + +--- + +## ๐Ÿงช Testing & Validation + +### Unit Tests + +**Test File:** `tests/test-network-modes.sh` (new) + +```bash +#!/bin/sh +# Network Modes v0.3.5 Test Suite + +test_wireguard_keys() { + echo "Testing WireGuard key generation..." + result=$(ubus call luci.network-modes generate_wireguard_keys) + privkey=$(echo "$result" | jsonfilter -e '@.private_key') + pubkey=$(echo "$result" | jsonfilter -e '@.public_key') + + [ ${#privkey} -eq 44 ] || { echo "FAIL: Private key length"; return 1; } + [ ${#pubkey} -eq 44 ] || { echo "FAIL: Public key length"; return 1; } + + echo "PASS: WireGuard keys generated" +} + +test_squid_config() { + echo "Testing Squid configuration..." + uci set network-modes.router.web_proxy='squid' + result=$(ubus call luci.network-modes generate_squid_config) + + [ -f /etc/squid/squid.conf ] || { echo "FAIL: Squid config not created"; return 1; } + grep -q "http_port 3128 transparent" /etc/squid/squid.conf || { echo "FAIL: Wrong port"; return 1; } + + echo "PASS: Squid config generated" +} + +test_nginx_vhost() { + echo "Testing Nginx virtual host deployment..." + uci set network-modes.router.https_frontend='1' + uci set network-modes.vhost1=vhost + uci set network-modes.vhost1.domain='test.example.com' + uci set network-modes.vhost1.backend_ip='192.168.1.100' + uci set network-modes.vhost1.backend_port='8080' + uci commit network-modes + + result=$(ubus call luci.network-modes deploy_nginx_vhosts) + vhost_count=$(echo "$result" | jsonfilter -e '@.vhosts_deployed') + + [ "$vhost_count" -ge 1 ] || { echo "FAIL: No vhosts deployed"; return 1; } + [ -f /etc/nginx/conf.d/vhost-vhost1.conf ] || { echo "FAIL: Vhost config not created"; return 1; } + + echo "PASS: Nginx vhost deployed" +} + +test_80211r_config() { + echo "Testing 802.11r configuration..." + uci set network-modes.accesspoint.ieee80211r='1' + result=$(ubus call luci.network-modes configure_80211r) + + mobility_domain=$(uci -q get wireless.@wifi-iface[0].mobility_domain) + [ -n "$mobility_domain" ] || { echo "FAIL: No mobility domain"; return 1; } + + echo "PASS: 802.11r configured (MDID: $mobility_domain)" +} + +test_pcap_capture() { + echo "Testing packet capture..." + uci set network-modes.sniffer.pcap_capture='1' + result=$(ubus call luci.network-modes start_packet_capture) + + pid=$(echo "$result" | jsonfilter -e '@.pid') + [ -n "$pid" ] && kill -0 "$pid" 2>/dev/null || { echo "FAIL: tcpdump not running"; return 1; } + + killall tcpdump + echo "PASS: Packet capture started" +} + +# Run all tests +test_wireguard_keys +test_squid_config +test_nginx_vhost +test_80211r_config +test_pcap_capture + +echo "" +echo "Test suite completed." +``` + +--- + +### Integration Tests + +**Test Scenarios:** + +1. **Router Mode with Squid + Nginx** + - Enable web_proxy=squid + - Add 2 virtual hosts + - Issue Let's Encrypt certificates + - Verify transparent proxy redirects HTTP traffic + - Verify Nginx proxies HTTPS to backends + +2. **Access Point with 802.11r/k/v** + - Enable all WiFi optimization flags + - Connect 2 devices + - Force roaming between APs + - Verify FT handshake occurs (<50ms) + - Check neighbor reports in hostapd + +3. **Relay Mode with WireGuard** + - Generate WireGuard keys + - Configure peer endpoint + - Apply MTU/MSS clamping + - Enable TCP BBR + - Verify tunnel UP + - Test throughput (should be >90% of baseline) + +4. **Sniffer Mode with PCAP** + - Start packet capture with filter "port 80" + - Generate HTTP traffic + - Verify PCAP files created + - Check rotation works (10 files max) + - Cleanup old captures (7 day retention) + +--- + +## ๐Ÿ“‹ Pre-Release Checklist + +### Code Quality +- [ ] All RPCD methods return valid JSON +- [ ] Error handling for missing dependencies (wireguard-tools, squid, nginx, tcpdump) +- [ ] Input validation for user-provided data (domains, IPs, filters) +- [ ] No hardcoded passwords or secrets +- [ ] Shellcheck passes on all RPCD scripts +- [ ] No placeholder comments remain + +### Functionality +- [ ] WireGuard keys generate correctly +- [ ] Squid config includes cache and ACLs +- [ ] Nginx vhosts proxy to backends +- [ ] Let's Encrypt certificates issue successfully +- [ ] 802.11r MDID is consistent across APs +- [ ] tcpdump captures with BPF filters +- [ ] PCAP rotation works (file count limit) +- [ ] All services start/stop/reload correctly + +### Safety +- [ ] Rollback mechanism restores service configs +- [ ] Backup includes /etc/squid/, /etc/nginx/, /etc/acme/ +- [ ] Config validation before apply +- [ ] No destructive operations without confirmation +- [ ] Service failures don't brick the router + +### Documentation +- [ ] README.md updated with real command examples +- [ ] Dependency list includes new packages +- [ ] Configuration examples for each mode +- [ ] Troubleshooting section added +- [ ] API documentation for new RPCD methods + +### Testing +- [ ] Unit tests pass (test-network-modes.sh) +- [ ] Integration tests pass (all 4 modes) +- [ ] Manual testing on real hardware +- [ ] Performance benchmarks (WireGuard throughput, proxy latency) +- [ ] Security audit (no command injection, XSS in UI) + +--- + +## ๐Ÿšข Release Process + +### Version Bump +```bash +# Update Makefile +sed -i 's/PKG_VERSION:=0.3.4/PKG_VERSION:=0.3.5/' luci-app-network-modes/Makefile +sed -i 's/PKG_RELEASE:=1/PKG_RELEASE:=1/' luci-app-network-modes/Makefile + +# Update README.md +sed -i 's/Version: 0.3.4/Version: 0.3.5/' luci-app-network-modes/README.md + +# Update MODULE_STATUS.md +# (Update implementation percentage to 85-90%) +``` + +### Git Workflow +```bash +# Commit changes +git add luci-app-network-modes/ +git commit -m "feat(network-modes): Implement v0.3.5 production features + +- WireGuard: Key generation, peer config, MTU clamping, TCP BBR +- Web Proxy: Squid config, transparent proxy, DoH +- HTTPS: Nginx vhosts, Let's Encrypt, SSL validation +- WiFi: 802.11r/k/v implementation, band steering +- Sniffer: tcpdump integration, PCAP rotation + +Closes #XX, #YY, #ZZ" + +# Tag release +git tag -a v0.3.5 -m "Release v0.3.5: Production Feature Completion + +Major Features: +- WireGuard relay with automatic key management +- Web proxy with Squid/TinyProxy support +- HTTPS reverse proxy with Let's Encrypt +- Advanced WiFi (802.11r/k/v) +- Packet capture with rotation + +Testing: +- All unit tests passing +- Integration tests on x86_64, ARM64 +- Performance benchmarks included + +Breaking Changes: None +Migration: Automatic (UCI config preserved)" + +# Push +git push origin master --tags +``` + +### Build & Deploy +```bash +# Build packages for all architectures +./secubox-tools/local-build.sh build luci-app-network-modes + +# Test on staging router +scp build/x86-64/luci-app-network-modes_0.3.5-1_all.ipk root@staging:/tmp/ +ssh root@staging "opkg install /tmp/luci-app-network-modes_0.3.5-1_all.ipk" + +# Deploy to production +# (After testing succeeds) +``` + +--- + +## ๐ŸŽ“ Implementation Guidelines + +### Code Style +- Follow existing RPCD patterns in `luci.network-modes` +- Use UCI for all configuration storage +- Return JSON with `{"success": true/false}` for all methods +- Log errors to `/var/log/network-modes.log` +- Use helper functions for repetitive tasks + +### Security Best Practices +- Validate all user input (domains, IPs, ports, filters) +- Escape shell variables: `"$var"` not `$var` +- Use `uci -q get` to avoid errors on missing configs +- Check command existence: `command -v cmd >/dev/null` +- Don't store passwords in UCI (use /etc/shadow or encrypted storage) + +### Performance Considerations +- Don't restart services unnecessarily (use reload) +- Cache expensive operations (WireGuard key generation) +- Use background jobs for long operations (Let's Encrypt) +- Implement timeouts for external commands +- Clean up temp files after operations + +### Error Handling +```bash +# Example error handling pattern +do_operation() { + local result + result=$(some_command 2>&1) || { + logger -t network-modes "ERROR: some_command failed: $result" + printf '{"success": false, "error": "%s"}\n' "$result" + return 1 + } + + printf '{"success": true, "result": "%s"}\n' "$result" +} +``` + +--- + +## ๐Ÿ“Š Success Metrics + +**Completion Targets:** +- Implementation: 85-90% (up from 50-60%) +- Feature Parity: 18/18 RPCD methods fully functional +- Test Coverage: 90%+ unit tests passing +- Documentation: 100% of new features documented +- Performance: <5% overhead vs manual configuration + +**User Impact:** +- One-click WireGuard VPN setup (vs 30+ manual commands) +- Automatic HTTPS with Let's Encrypt (vs hours of nginx config) +- Professional web proxy in 2 clicks (vs Squid complexity) +- WiFi roaming optimization (vs hostapd expertise required) +- Network-wide packet capture (vs tcpdump command-line) + +--- + +## ๐Ÿ”— References + +**OpenWrt Documentation:** +- [UCI Configuration](https://openwrt.org/docs/guide-user/base-system/uci) +- [WireGuard Setup](https://openwrt.org/docs/guide-user/services/vpn/wireguard/start) +- [Nginx on OpenWrt](https://openwrt.org/docs/guide-user/services/webserver/nginx) +- [hostapd WiFi](https://openwrt.org/docs/guide-user/network/wifi/basic) + +**External Tools:** +- [Squid Proxy](http://www.squid-cache.org/Doc/) +- [Let's Encrypt ACME](https://letsencrypt.org/docs/) +- [tcpdump Filters](https://www.tcpdump.org/manpages/pcap-filter.7.html) +- [802.11r/k/v Guide](https://www.intel.com/content/www/us/en/support/articles/000054799/) + +**SecuBox Integration:** +- [DEVELOPMENT-GUIDELINES.md](../DEVELOPMENT-GUIDELINES.md) +- [QUICK-START.md](../QUICK-START.md) +- [MODULE_STATUS.md](../DOCS/MODULE_STATUS.md) + +--- + +**Next Steps:** +1. Review this codex with team +2. Assign tasks to developers +3. Set up development branches +4. Begin Phase 1 (WireGuard) implementation +5. Weekly progress reviews + +**Questions/Feedback:** Contact maintainers or open GitHub issue + +--- + +*Generated: 2025-12-28* +*Codex Version: 1.0* +*Target Release: 2025-01-15*