chore: update device-agent submodule

agent: console X survives, UTF-8 encoding, debug-gated heartbeat
server: reject heartbeat for suspended devices (403)

.gitea/workflows/build_dashboard.yaml

@@ -23,22 +23,34 @@ jobs:
         with:
           node-version: '24'
 
+      - name: Hash source files
+        id: hash-src
+        run: echo "hash=$(find apps/dashboard-ui -type f \( -name '*.vue' -o -name '*.ts' -o -name '*.js' -o -name '*.css' -o -name '*.json' -o -name '*.html' \) | sort | xargs sha256sum | sha256sum | cut -d' ' -f1)" >> "$GITHUB_OUTPUT"
+
+      - uses: actions/cache@v3
+        id: cache-build
+        with:
+          path: apps/dashboard-ui/dist
+          key: build-dashboard-${{ steps.hash-src.outputs.hash }}
+
       - name: Hash package-lock
         id: hash-npm
         run: echo "hash=$(sha256sum apps/dashboard-ui/package-lock.json | cut -d' ' -f1)" >> "$GITHUB_OUTPUT"
 
       - uses: actions/cache@v3
+        id: cache-npm
         with:
-          path: |
+          path: ~/.npm
-            ~/.npm
           key: npm-dashboard-${{ steps.hash-npm.outputs.hash }}
           restore-keys: npm-dashboard-
 
       - name: Install
+        if: steps.cache-build.outputs.cache-hit != 'true'
         working-directory: apps/dashboard-ui
         run: npm ci || npm install
 
       - name: Build
+        if: steps.cache-build.outputs.cache-hit != 'true'
         working-directory: apps/dashboard-ui
         run: npm run build
 

.gitea/workflows/build_device_agent.yaml

@@ -24,7 +24,29 @@ jobs:
           go-version: '1.26'
           cache: true
 
+      - uses: https://gitea.com/actions/go-hashfiles@v0.0.1
+        id: hash-src
+        with:
+          patterns: |
+            apps/device-agent/**/*.go
+            apps/device-agent/go.mod
+            apps/device-agent/go.sum
+
+      - uses: actions/cache@v3
+        id: cache-build
+        with:
+          path: apps/device-agent/bin
+          key: build-device-agent-${{ steps.hash-src.outputs.hash }}
+
+      - name: Generate Windows resources (UAC manifest + icon)
+        if: steps.cache-build.outputs.cache-hit != 'true'
+        working-directory: apps/device-agent
+        run: |
+          go install github.com/tc-hib/go-winres@latest
+          go-winres make
+
       - name: Build all platforms
+        if: steps.cache-build.outputs.cache-hit != 'true'
         working-directory: apps/device-agent
         shell: bash
         run: |
@@ -37,7 +59,7 @@ jobs:
             if [ "$GOOS" = "windows" ]; then EXT=".exe"; fi
             OUT="bin/nexus-device-agent-${GOOS}-${GOARCH}${EXT}"
             echo "Building $OUT ..."
-            CGO_ENABLED=0 GOOS="$GOOS" GOARCH="$GOARCH" go build -o "$OUT" .
+            CGO_ENABLED=0 GOOS="$GOOS" GOARCH="$GOARCH" go build -ldflags="-s -w" -o "$OUT" .
           done
           echo "=== Build output ==="
           ls -la bin/

.gitea/workflows/build_server_core.yaml

@@ -24,13 +24,31 @@ jobs:
           go-version: '1.26'
           cache: true
 
+      - uses: https://gitea.com/actions/go-hashfiles@v0.0.1
+        id: hash-src
+        with:
+          patterns: |
+            apps/server-core/**/*.go
+            apps/server-core/go.mod
+            apps/server-core/go.sum
+
+      - uses: actions/cache@v3
+        id: cache-build
+        with:
+          path: |
+            apps/server-core/bin
+            apps/server-core/docs
+          key: build-server-core-${{ steps.hash-src.outputs.hash }}
+
       - name: Generate Swagger docs
+        if: steps.cache-build.outputs.cache-hit != 'true'
         working-directory: apps/server-core
         run: |
           go install github.com/swaggo/swag/cmd/swag@v1.16.6
           swag init -g main.go --parseDependency --parseInternal
 
       - name: Build
+        if: steps.cache-build.outputs.cache-hit != 'true'
         working-directory: apps/server-core
         run: go build -o bin/server-core .
 

.gitea/workflows/ci.yml

@@ -10,9 +10,11 @@ on:
       - 'v[0-9]*.[0-9]*.[0-9]'
 
 jobs:
-  # --- TESTS (test tags + stable release tags) ---
+  # ====================================================================
+  # TESTS — test tags only
+  # ====================================================================
   server-core-test:
-    if: contains(gitea.ref_name, 'test') || (!contains(gitea.ref_name, 'dev') && !contains(gitea.ref_name, 'beta'))
+    if: contains(gitea.ref_name, 'test')
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
@@ -26,17 +28,13 @@ jobs:
       - uses: actions/setup-go@v5
         with:
           go-version: '1.26'
-      - name: Generate swagger docs
+          cache: true
-        working-directory: apps/server-core
-        run: |
-          go install github.com/swaggo/swag/cmd/swag@v1.16.6
-          swag init -g main.go --parseDependency --parseInternal
       - name: Test (skip nftables - needs root)
         working-directory: apps/server-core
         run: go test $(go list ./... | grep -v internal/firewall) -tags dev -cover -count=1
 
   device-agent-test:
-    if: contains(gitea.ref_name, 'test') || (!contains(gitea.ref_name, 'dev') && !contains(gitea.ref_name, 'beta'))
+    if: contains(gitea.ref_name, 'test')
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
@@ -50,12 +48,13 @@ jobs:
       - uses: actions/setup-go@v5
         with:
           go-version: '1.26'
+          cache: true
       - name: Test
         working-directory: apps/device-agent
         run: go test ./... -cover
 
   dashboard-test:
-    if: contains(gitea.ref_name, 'test') || (!contains(gitea.ref_name, 'dev') && !contains(gitea.ref_name, 'beta'))
+    if: contains(gitea.ref_name, 'test')
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
@@ -76,37 +75,45 @@ jobs:
         working-directory: apps/dashboard-ui
         run: npm run build
 
-  # --- BUILD + RELEASE (dev/beta/release tags) ---
+  # ====================================================================
+  # BUILD — after tests pass (release) or directly (dev/beta)
+  # ====================================================================
   build-server-core:
-    if: always() && !contains(gitea.ref_name, 'test') && !failure()
+    if: always() && !contains(gitea.ref_name, 'test') && !failure() && !cancelled()
     needs: [server-core-test, device-agent-test, dashboard-test]
     runs-on: ubuntu-latest
     uses: ./.gitea/workflows/build_server_core.yaml
     secrets: inherit
 
   build-device-agent:
-    if: always() && !contains(gitea.ref_name, 'test') && !failure()
+    if: always() && !contains(gitea.ref_name, 'test') && !failure() && !cancelled()
     needs: [server-core-test, device-agent-test, dashboard-test]
     runs-on: ubuntu-latest
     uses: ./.gitea/workflows/build_device_agent.yaml
     secrets: inherit
 
   build-dashboard:
-    if: always() && !contains(gitea.ref_name, 'test') && !failure()
+    if: always() && !contains(gitea.ref_name, 'test') && !failure() && !cancelled()
     needs: [server-core-test, device-agent-test, dashboard-test]
     runs-on: ubuntu-latest
     uses: ./.gitea/workflows/build_dashboard.yaml
     secrets: inherit
 
+  # ====================================================================
+  # DOCS — after builds pass, release tags only
+  # ====================================================================
   build-docs:
-    if: always() && !contains(gitea.ref_name, 'test') && !failure()
+    if: always() && !contains(gitea.ref_name, 'dev') && !contains(gitea.ref_name, 'beta') && !contains(gitea.ref_name, 'test') && !failure() && !cancelled()
-    needs: [server-core-test, device-agent-test, dashboard-test]
+    needs: [build-server-core, build-device-agent, build-dashboard]
     runs-on: ubuntu-latest
     uses: ./.gitea/workflows/docs_call.yaml
     secrets: inherit
 
+  # ====================================================================
+  # RELEASE — after everything passes
+  # ====================================================================
   release:
-    if: always() && !contains(gitea.ref_name, 'test') && !failure()
+    if: always() && !contains(gitea.ref_name, 'test') && !failure() && !cancelled()
     needs: [build-server-core, build-device-agent, build-dashboard, build-docs]
     uses: ./.gitea/workflows/release_call.yaml
     with:

.gitea/workflows/docs_call.yaml

@@ -21,6 +21,17 @@ jobs:
         with:
           node-version: '24'
 
+      - name: Hash package-lock
+        id: hash-npm
+        run: echo "hash=$(sha256sum apps/docs/package-lock.json 2>/dev/null || echo 'none') | cut -d' ' -f1)" >> "$GITHUB_OUTPUT"
+
+      - uses: actions/cache@v3
+        with:
+          path: |
+            ~/.npm
+          key: npm-docs-${{ steps.hash-npm.outputs.hash }}
+          restore-keys: npm-docs-
+
       - name: Install
         working-directory: apps/docs
         run: npm ci || npm install

.gitignore

@@ -36,6 +36,8 @@ temp_*
 # Build output
 dist/
 /dist/
+.tests/
+tests/
 
 # OpenCode
 connect_remote.txt

AGENTS.md

@@ -1,11 +1,22 @@
 # PROJECT KNOWLEDGE BASE
 
-**Generated:** 2026-05-22
+**Generated:** 2026-06-20
-**Commit:** `92051d5`
 **Branch:** `main`
 
 ## OVERVIEW
-NexusGuard SD-WAN Suite — Enterprise Zero-Trust SD-WAN with WireGuard tunneling, centralized IPAM, and real-time nftables network isolation. Monorepo with 3 git submodules: Go backend (Gin), Vue 3 dashboard, Go device agent.
+NexusGuard SD-WAN Suite: Enterprise Zero-Trust SD-WAN with WireGuard tunneling, centralized IPAM, and real-time nftables network isolation. Monorepo with 3 git submodules: Go backend (Gin), Vue 3 dashboard, Go device agent.
+
+## TOPOLOGY
+
+| Host | SSH | Role |
+|------|-----|------|
+| Production server | `root@172.20.8.191` | Runs server-core, Postgres, Redis, nginx, nftables, WireGuard |
+| Gitea server | `root@172.20.8.92` | Private Git hosting (`git.datadunia.com`) |
+
+- Server project folder: `/root/Nexus-Guard-Suite`
+- Deploy: `./update.sh` (don't build manually)
+- Actual WireGuard wg0 IP: `10.172.21.1/24` (on server 172.20.8.191)
+- Agent WG IPs: dynamic from pool `10.172.21.0/24`
 
 ## STRUCTURE
 ```
@@ -20,7 +31,7 @@ NexusGuard SD-WAN Suite — Enterprise Zero-Trust SD-WAN with WireGuard tunnelin
 ├── setup.sh              # First-run: generate .env + random keys
 ├── update.sh             # Docker update: pull/build/migrate
 ├── nexusguard-install.sh # Native install (systemd + nginx)
-├── nexusguard-uninstall.sh # Native uninstall
+├── nexusguard-uninstall.sh
 ├── .env.example          # DB/JWT/SALT/VITE config template
 ├── .gitmodules           # 3 submodules → git.datadunia.com
 └── .opencode/            # IDE agent config (tooling, not project code)
@@ -35,16 +46,78 @@ NexusGuard SD-WAN Suite — Enterprise Zero-Trust SD-WAN with WireGuard tunnelin
 | Backend core | `apps/server-core/internal/` | auth, config, firewall, heartbeat, ipam, models, wgmanager |
 | Dev migration | `apps/server-core/main_dev.go` | GORM AutoMigrate (build tag `dev`) |
 | Firewall rules | `apps/server-core/internal/firewall/` | nftables Linux rules |
+| gRPC signaling | `apps/server-core/signaling/` | Manager + Server: gRPC session tracking, Connect handler, recv loop |
 | Dashboard views | `apps/dashboard-ui/src/views/` | Vue SFC pages |
 | Dashboard API client | `apps/dashboard-ui/src/api/` | Axios API modules |
 | Dashboard stores | `apps/dashboard-ui/src/stores/` | Pinia state stores |
 | Agent client | `apps/device-agent/internal/client/` | Provisioning + heartbeat |
+| Agent signaling | `apps/device-agent/internal/signaling/` | gRPC connect with fallback + reconnect |
 | Agent tunnel | `apps/device-agent/internal/tunnel/` | Memory-injected WireGuard |
 | Shared crypto | `apps/*/shared/crypto/encryptor.go` | AES-256-GCM (duplicated identical) |
 | CI workflows | `apps/*/.gitea/workflows/build.yml` | Gitea Actions per submodule |
 | Build config | `apps/dashboard-ui/vite.config.ts` | Vite 8 + Vue + TailwindCSS v4 |
 | Source of truth | `apps/server-core/docs/` | API_SPEC, KEY_ROTATION, PEER_DISCOVERY |
-| Plan guardrails | `.sisyphus/plans/` | Anti-patterns, "Must NOT do" rules |
+
+## SIGNALING ARCHITECTURE (CRITICAL)
+
+### Topology
+```
+┌──────────────┐         ┌─────────────────┐         ┌──────────────┐
+│  Dashboard   │──HTTP──▶│  Server Core    │◀─WG────▶│ Device Agent │
+│  (Vue 3)     │  :8080  │  (Go/Gin)       │  :51820 │  (Go)        │
+└──────────────┘         │                 │         └──────────────┘
+                         │  Port 8080:     │              │
+                         │  - HTTP API     │         ┌────┴────┐
+                         │  - gRPC Signal  │         │ TUN (wg)│
+                         │  (cmux)         │         │ Memory  │
+                         └─────────────────┘         └─────────┘
+```
+
+### Transport Fallback Chain (Agent → Server)
+1. gRPC via HTTPS domain (TLS) → `italy-twenty.gl.at.ply.gg:443`
+2. gRPC via WireGuard IP (insecure, tunnel-encrypted) → `10.172.21.1:8080`
+3. HTTP heartbeat (fallback) → `serverURL/api/v1/heartbeat`
+
+### Heartbeat = PRIMARY Channel
+Always runs. Handles:
+- Health check (30s interval)
+- Config sync (detects config changes → rebuild tunnel)
+- Handshake monitoring (rebuilds tunnel if lastHandshake > 120s)
+- Recovery after failure (wasFailing → OnRecovered → full rebuild)
+
+### gRPC = BONUS Channel
+Best-effort. Handles:
+- Real-time commands: Suspend, Resume, ConfigUpdate, Reconnect, Disconnect
+- StatusReport from agent (tunnel_up, lastHandshake, state)
+- Ping/Pong keepalive (20s)
+
+### gRPC Port Multiplexing
+HTTP + gRPC share port 8080 via `cmux`:
+- Server: `cmux.New(lis)` → match gRPC by `content-type` header, match HTTP by `Any()`
+- Agent connects to same port for both HTTP API and gRPC
+
+### Key Design Decisions
+- Agent NEVER destroys tunnel on heartbeat failure — only rebuilds
+- `OnFailure = log only`, `OnRecovered = full rebuild`
+- gRPC OnDisconnect/OnGRPCFailed just log — heartbeat continues
+- Heartbeat reads `last_handshake_time_sec` from WG IPC to detect stale tunnel
+- gRPC StatusReport sends handshake age to server every 30s
+- Server WG IP read from actual kernel interface (`net.InterfaceByName`), NOT from stale DB
+
+### Agent Connection Lifecycle
+1. Provision → register with server, get WireGuard config
+2. Start tunnel (memory-injected, no disk files)
+3. Start heartbeat (always, primary channel)
+4. Start gRPC (if ServerWGIP available, bonus channel)
+5. On heartbeat config change → rebuild tunnel
+6. On heartbeat stale handshake → rebuild tunnel
+7. On heartbeat failure+recovery → rebuild tunnel
+8. On gRPC suspend → stop tunnel, heartbeat continues
+9. On gRPC resume → rebuild tunnel from server config
+
+### Protobuf Messages
+- **Agent → Server**: HelloMessage, HeartbeatAck, StatusReport, PingMessage
+- **Server → Agent**: ConfigUpdate, SuspendCommand, ResumeCommand, ReconnectCommand, DisconnectCommand, KeepAlive, PongMessage
 
 ## CODE MAP
 | Symbol | Type | Location | Role |
@@ -60,8 +133,15 @@ NexusGuard SD-WAN Suite — Enterprise Zero-Trust SD-WAN with WireGuard tunnelin
 | `firewall.InitNetwork()` | func | `apps/server-core/internal/firewall/` | nftables table/set creation |
 | `ipam.AllocateIP()` | func | `apps/server-core/internal/ipam/` | IP pool allocation from CIDR |
 | `wgmanager.SetConfig()` | func | `apps/server-core/internal/wgmanager/` | WireGuard config push |
+| `wgmanager.GetInterfaceAddress()` | func | `apps/server-core/internal/wgmanager/` | Read actual WG interface IP from kernel |
 | `models.AutoMigrate()` | func | `apps/server-core/internal/models/` | GORM schema migration |
 | `encrypt()` / `decrypt()` | func | `apps/*/shared/crypto/encryptor.go` | AES-256-GCM (identical) |
+| `StartHeartbeat()` | func | `apps/device-agent/internal/client/heartbeat.go` | Heartbeat loop + handshake monitoring |
+| `checkHandshake()` | func | `apps/device-agent/internal/client/heartbeat.go` | Read WG IPC handshake time |
+| `ConnectAndRun()` | func | `apps/device-agent/internal/signaling/client.go` | gRPC connect with fallback + reconnect |
+| `statusLoop()` | func | `apps/device-agent/internal/signaling/client.go` | Sends StatusReport every 30s |
+| `NewManager()` | func | `apps/server-core/signaling/manager.go` | gRPC session tracking |
+| `NewServer()` | func | `apps/server-core/signaling/server.go` | gRPC Connect handler + recv loop |
 
 ## CONVENTIONS
 - **Go**: Standard layout (`main.go` in root, `internal/`, `api/`)
@@ -79,7 +159,7 @@ NexusGuard SD-WAN Suite — Enterprise Zero-Trust SD-WAN with WireGuard tunnelin
 
 ## ANTI-PATTERNS (THIS PROJECT)
 - **NEVER** `nft flush table` — only atomic add/remove
-- **NEVER** commit temp/debug/test files (`nft-fix.sh`, `temp_*.txt` etc) in project root use ./tests folder and dont commit
+- **NEVER** commit temp/debug/test files (`nft-fix.sh`, `temp_*.txt` etc) in project root; use `./tests` folder
 - **NEVER** log plaintext or encryption keys
 - **NEVER** reopen completed phases/commits — fix forward only
 - **NEVER** rebuild `shared/crypto/encryptor.go` — copy identical file
@@ -200,10 +280,43 @@ go run -tags dev ./apps/server-core -create-admin -user admin -pass "..."
 sudo /usr/local/bin/nexusguard-server -create-admin -user admin -pass "..."
 ```
 
+## heartbeat server <-> device-agent
+
+Konsep yang Benar
+Heartbeat = satu konsep, tiga jalur transport:
+
+0	Transport	Protocol	Endpoint	Kapan Dipakai
+1	gRPC via domain (HTTPS proxy)	gRPC bidi stream	api-nexus.datadunia.com:443	Pertama dicoba
+2	gRPC via WG IP (direct)	gRPC bidi stream	10.172.21.1:8080	Fallback jika proxy swallowed
+3	HTTP API	REST POST	/api/v1/heartbeat	Fallback terakhir / always running
+Satu konsep yang sama: kirim config_hash + last_handshake + tunnel_up → server compare → respond dengan config jika berubah.
+
+Yang Perlu Diperbaiki
+client.go: Perlu ada gRPC heartbeat loop (kirim HeartbeatRequest via stream periodik) + handle HeartbeatResponse
+heartbeat.go: HTTP heartbeat tetap ada sebagai fallback
+Transport switching: Saat gRPC connected → heartbeat via gRPC. Saat gRPC disconnected → heartbeat via HTTP
+handler.go: Perlu handleHeartbeatResponse untuk process config dari gRPC heartbeat
+Server manager.go: Perlu sendMu untuk prevent concurrent stream.Send()
+Alur yang Benar (setelah perbaikan)
+Agent Start
+  → Provision (HTTP) → config pertama dari HTTP API → build tunnel
+  → Start HTTP heartbeat (always running, fallback transport)
+  → Start gRPC (HTTPS → WG IP)
+  
+gRPC Connected:
+  → establishStream: kirim HelloMessage → terima ConfigUpdate (verify only, jangan rebuild)
+  → heartbeatLoop: kirim HeartbeatRequest via gRPC setiap 30s
+  → Server respond: HeartbeatResponse (config_changed? → rebuild via handler)
+  → dispatch: handle Suspend/Resume/ConfigUpdate/Reconnect/Disconnect
+
+gRPC Disconnected:
+  → HTTP heartbeat continues (unaffected)
+  → gRPC reconnect loop
+  → When reconnected → switch heartbeat back to gRPC
+  
 ## NOTES
 - Submodules → private Gitea (`git.datadunia.com`); CI via Gitea Actions per submodule
 - Go versions diverge: server-core `1.25.7`, device-agent `1.25.1`
 - No root linter configs (`.golangci.yml`, `.eslintrc`, `.editorconfig`)
 - Shell scripts use deprecated `docker-compose` v1, Makefile uses `docker compose` v2
-- Root has stale artifacts: `connect_remote.txt`, `temp_section*.txt`
 - `package.json` name is `"temp-ui"` (stale scaffold remnant)