migrate

Wavelet/internal/apps/openflare/agent/auth_cache.go

@@ -0,0 +1,143 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package agent
+
+import (
+	"context"
+	"errors"
+	"strings"
+	"sync"
+	"time"
+
+	"github.com/Rain-kl/Wavelet/internal/model"
+	"gorm.io/gorm"
+)
+
+const (
+	agentTokenPositiveCacheTTL = 2 * time.Minute
+	agentTokenNegativeCacheTTL = 10 * time.Minute
+)
+
+type cachedAgentNode struct {
+	node      *model.OpenFlareNode
+	expiresAt time.Time
+}
+
+type accessTokenAuthCache struct {
+	mu              sync.RWMutex
+	positive        map[string]cachedAgentNode
+	negative        map[string]time.Time
+	now             func() time.Time
+	loadNodeByToken func(context.Context, string) (*model.OpenFlareNode, error)
+}
+
+var tokenCache = newAccessTokenAuthCache()
+
+func newAccessTokenAuthCache() *accessTokenAuthCache {
+	return &accessTokenAuthCache{
+		positive: make(map[string]cachedAgentNode),
+		negative: make(map[string]time.Time),
+		now:      time.Now,
+		loadNodeByToken: func(ctx context.Context, token string) (*model.OpenFlareNode, error) {
+			return model.GetOpenFlareNodeByAccessToken(ctx, token)
+		},
+	}
+}
+
+func (c *accessTokenAuthCache) authenticate(ctx context.Context, token string) (*model.OpenFlareNode, error) {
+	now := c.now()
+	if node, ok := c.getNode(token, now); ok {
+		return node, nil
+	}
+	if c.isMissing(token, now) {
+		return nil, gorm.ErrRecordNotFound
+	}
+
+	node, err := c.loadNodeByToken(ctx, token)
+	if err != nil {
+		if errors.Is(err, gorm.ErrRecordNotFound) {
+			c.storeMissing(token, now.Add(agentTokenNegativeCacheTTL))
+		}
+		return nil, err
+	}
+
+	c.storeNode(token, node)
+	return cloneNode(node), nil
+}
+
+func (c *accessTokenAuthCache) getNode(token string, now time.Time) (*model.OpenFlareNode, bool) {
+	c.mu.RLock()
+	entry, ok := c.positive[token]
+	c.mu.RUnlock()
+	if !ok {
+		return nil, false
+	}
+	if now.After(entry.expiresAt) {
+		c.mu.Lock()
+		delete(c.positive, token)
+		c.mu.Unlock()
+		return nil, false
+	}
+	return cloneNode(entry.node), true
+}
+
+func (c *accessTokenAuthCache) isMissing(token string, now time.Time) bool {
+	c.mu.RLock()
+	expiresAt, ok := c.negative[token]
+	c.mu.RUnlock()
+	if !ok {
+		return false
+	}
+	if now.After(expiresAt) {
+		c.mu.Lock()
+		delete(c.negative, token)
+		c.mu.Unlock()
+		return false
+	}
+	return true
+}
+
+func (c *accessTokenAuthCache) storeNode(token string, node *model.OpenFlareNode) {
+	if token == "" || node == nil {
+		return
+	}
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	delete(c.negative, token)
+	c.positive[token] = cachedAgentNode{
+		node:      cloneNode(node),
+		expiresAt: c.now().Add(agentTokenPositiveCacheTTL),
+	}
+}
+
+func (c *accessTokenAuthCache) storeMissing(token string, expiresAt time.Time) {
+	if token == "" {
+		return
+	}
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	delete(c.positive, token)
+	c.negative[token] = expiresAt
+}
+
+func (c *accessTokenAuthCache) reset() {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	c.positive = make(map[string]cachedAgentNode)
+	c.negative = make(map[string]time.Time)
+}
+
+// ResetAuthCacheForTest clears the in-memory access token cache for integration tests.
+func ResetAuthCacheForTest() {
+	tokenCache.reset()
+}
+
+// AuthenticateAccessToken validates X-Agent-Token against of_nodes.access_token.
+func AuthenticateAccessToken(ctx context.Context, token string) (*model.OpenFlareNode, error) {
+	token = strings.TrimSpace(token)
+	if token == "" {
+		return nil, errors.New(errMissingAgentToken)
+	}
+	return tokenCache.authenticate(ctx, token)
+}

Wavelet/internal/apps/openflare/agent/config.go

@@ -0,0 +1,98 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package agent
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"strings"
+	"time"
+
+	"github.com/Rain-kl/Wavelet/internal/db"
+	"gorm.io/gorm"
+)
+
+type configVersionRecord struct {
+	ID               uint      `gorm:"primaryKey"`
+	Version          string    `gorm:"column:version"`
+	SnapshotJSON     string    `gorm:"column:snapshot_json"`
+	SupportFilesJSON string    `gorm:"column:support_files_json"`
+	Checksum         string    `gorm:"column:checksum"`
+	IsActive         bool      `gorm:"column:is_active"`
+	CreatedAt        time.Time `gorm:"column:created_at"`
+}
+
+func (configVersionRecord) TableName() string {
+	return "of_config_versions"
+}
+
+func getActiveConfigMeta(ctx context.Context) (*ActiveConfigMeta, error) {
+	version, err := loadActiveConfigVersion(ctx)
+	if err != nil {
+		return nil, err
+	}
+	return &ActiveConfigMeta{
+		Version:  version.Version,
+		Checksum: version.Checksum,
+	}, nil
+}
+
+func getActiveConfigForAgent(ctx context.Context) (*ConfigResponse, error) {
+	version, err := loadActiveConfigVersion(ctx)
+	if err != nil {
+		return nil, err
+	}
+
+	var supportFiles []SupportFile
+	if strings.TrimSpace(version.SupportFilesJSON) != "" {
+		if err = json.Unmarshal([]byte(version.SupportFilesJSON), &supportFiles); err != nil {
+			return nil, err
+		}
+	}
+
+	return &ConfigResponse{
+		Version:          version.Version,
+		Checksum:         version.Checksum,
+		SourceConfigJSON: version.SnapshotJSON,
+		SupportFiles:     sourceSupportFiles(supportFiles),
+		CreatedAt:        version.CreatedAt,
+	}, nil
+}
+
+func loadActiveConfigVersion(ctx context.Context) (*configVersionRecord, error) {
+	conn := db.DB(ctx)
+	if conn == nil {
+		return nil, errors.New("database not initialized")
+	}
+	version := &configVersionRecord{}
+	err := conn.Where("is_active = ?", true).Order("id desc").First(version).Error
+	if err != nil {
+		return nil, err
+	}
+	return version, nil
+}
+
+func sourceSupportFiles(files []SupportFile) []SupportFile {
+	if len(files) == 0 {
+		return nil
+	}
+	result := make([]SupportFile, 0, len(files))
+	for _, file := range files {
+		if isRuntimeGeneratedSupportFile(file.Path) {
+			continue
+		}
+		result = append(result, file)
+	}
+	return result
+}
+
+func isRuntimeGeneratedSupportFile(path string) bool {
+	path = strings.TrimSpace(path)
+	return strings.HasPrefix(path, "runtime/")
+}
+
+func isActiveConfigNotFound(err error) bool {
+	return errors.Is(err, gorm.ErrRecordNotFound)
+}

Wavelet/internal/apps/openflare/agent/errs.go

@@ -0,0 +1,21 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package agent
+
+const (
+	errMissingAgentToken      = "缺少 Agent Token"
+	errInvalidAgentToken      = "无权进行此操作，Agent Token 无效"
+	errInvalidDiscoveryToken  = "无权进行此操作，注册 Token 无效"
+	errNodeMissingFromContext = "Node object missing from context"
+	errNoActiveConfig         = "当前没有激活版本"
+	errNodeNotFound           = "节点不存在"
+	errNodeIDRequired         = "node_id 不能为空"
+	errVersionRequired        = "version 不能为空"
+	errInvalidApplyResult     = "result 仅支持 success、warning 或 failed"
+	errIPRequired             = "ip 不能为空"
+	errIPInvalid              = "ip 格式无效"
+	errAgentVersionRequired   = "version 不能为空"
+	errNodeIDConflict         = "节点标识生成冲突，请重试"
+	errPagesPackageNotFound   = "Pages 部署包尚未实现"
+)

Wavelet/internal/apps/openflare/agent/helpers.go

@@ -0,0 +1,257 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package agent
+
+import (
+	"context"
+	"crypto/rand"
+	"encoding/hex"
+	"net"
+	"strings"
+	"time"
+
+	"github.com/Rain-kl/Wavelet/internal/model"
+)
+
+const (
+	openrestyStatusHealthy   = "healthy"
+	openrestyStatusUnhealthy = "unhealthy"
+	openrestyStatusUnknown   = "unknown"
+	releaseChannelStable     = "stable"
+)
+
+func newRandomToken() (string, error) {
+	buf := make([]byte, 16)
+	if _, err := rand.Read(buf); err != nil {
+		return "", err
+	}
+	return hex.EncodeToString(buf), nil
+}
+
+func newServerNodeID() (string, error) {
+	token, err := newRandomToken()
+	if err != nil {
+		return "", err
+	}
+	return "node-" + token, nil
+}
+
+func normalizeOpenrestyStatus(status string) string {
+	switch strings.ToLower(strings.TrimSpace(status)) {
+	case openrestyStatusHealthy:
+		return openrestyStatusHealthy
+	case openrestyStatusUnhealthy:
+		return openrestyStatusUnhealthy
+	default:
+		return openrestyStatusUnknown
+	}
+}
+
+func normalizeNodePayload(payload NodePayload) NodePayload {
+	payload.Name = strings.TrimSpace(payload.Name)
+	payload.IP = strings.TrimSpace(payload.IP)
+	payload.Version = strings.TrimSpace(payload.Version)
+	payload.ExtVersion = strings.TrimSpace(payload.ExtVersion)
+	payload.CurrentVersion = strings.TrimSpace(payload.CurrentVersion)
+	payload.LastError = truncateForDatabase(payload.LastError, 16000)
+	payload.OpenrestyStatus = normalizeOpenrestyStatus(payload.OpenrestyStatus)
+	payload.OpenrestyMessage = truncateForDatabase(payload.OpenrestyMessage, 16000)
+	return payload
+}
+
+func validateNodePayload(payload NodePayload) error {
+	if payload.IP == "" {
+		return errPayload(errIPRequired)
+	}
+	if net.ParseIP(payload.IP) == nil {
+		return errPayload(errIPInvalid)
+	}
+	if payload.Version == "" {
+		return errPayload(errAgentVersionRequired)
+	}
+	return nil
+}
+
+type payloadError string
+
+func (e payloadError) Error() string { return string(e) }
+
+func errPayload(message string) error { return payloadError(message) }
+
+func applyNodeRuntime(node *model.OpenFlareNode, payload NodePayload, preserveName bool) {
+	if !preserveName || strings.TrimSpace(node.Name) == "" {
+		if strings.TrimSpace(payload.Name) != "" {
+			node.Name = strings.TrimSpace(payload.Name)
+		}
+	}
+	if !node.IPManualOverride {
+		node.IP = strings.TrimSpace(payload.IP)
+	}
+	node.Version = strings.TrimSpace(payload.Version)
+	node.ExtVersion = strings.TrimSpace(payload.ExtVersion)
+	node.OpenrestyStatus = normalizeOpenrestyStatus(payload.OpenrestyStatus)
+	node.OpenrestyMessage = truncateForDatabase(payload.OpenrestyMessage, 16000)
+	node.Status = nodeStatusOnline
+	node.CurrentVersion = strings.TrimSpace(payload.CurrentVersion)
+	now := time.Now()
+	node.LastSeenAt = &now
+	node.LastError = truncateForDatabase(payload.LastError, 16000)
+}
+
+func truncateForDatabase(value string, max int) string {
+	if max <= 0 {
+		return ""
+	}
+	runes := []rune(strings.TrimSpace(value))
+	if len(runes) <= max {
+		return string(runes)
+	}
+	return string(runes[:max])
+}
+
+func resolveReportedNodeIP(reportedIP string, remoteAddr string) string {
+	reported := normalizeIP(reportedIP)
+	remote := normalizeRemoteAddr(remoteAddr)
+	if reported == "" {
+		return remote
+	}
+	if isPublicNodeIP(reported) {
+		return reported
+	}
+	if isPublicNodeIP(remote) {
+		return remote
+	}
+	return reported
+}
+
+func normalizeIP(raw string) string {
+	raw = strings.TrimSpace(raw)
+	if raw == "" {
+		return ""
+	}
+	host := raw
+	if strings.Contains(raw, ":") {
+		if h, _, err := net.SplitHostPort(raw); err == nil {
+			host = h
+		}
+	}
+	host = strings.TrimPrefix(host, "[")
+	host = strings.TrimSuffix(host, "]")
+	if ip := net.ParseIP(host); ip != nil {
+		return ip.String()
+	}
+	return ""
+}
+
+func normalizeRemoteAddr(remoteAddr string) string {
+	remoteAddr = strings.TrimSpace(remoteAddr)
+	if remoteAddr == "" {
+		return ""
+	}
+	host, _, err := net.SplitHostPort(remoteAddr)
+	if err != nil {
+		return normalizeIP(remoteAddr)
+	}
+	return normalizeIP(host)
+}
+
+func isPublicNodeIP(raw string) bool {
+	ip := net.ParseIP(strings.TrimSpace(raw))
+	if ip == nil {
+		return false
+	}
+	if ip.IsLoopback() || ip.IsPrivate() || ip.IsLinkLocalUnicast() || ip.IsLinkLocalMulticast() || ip.IsUnspecified() {
+		return false
+	}
+	return true
+}
+
+func buildAgentSettings(node *model.OpenFlareNode, updateNow bool, updateChannel string, updateTag string, restartOpenrestyNow bool) *Settings {
+	autoUpdate := false
+	if node != nil {
+		autoUpdate = node.AutoUpdateEnabled
+	}
+	if strings.TrimSpace(updateChannel) == "" {
+		updateChannel = releaseChannelStable
+	}
+	return &Settings{
+		HeartbeatInterval:       model.AgentHeartbeatInterval,
+		WebsocketUpgradeEnabled: model.AgentWebsocketUpgradeEnabled,
+		AutoUpdate:              autoUpdate,
+		UpdateRepo:              model.AgentUpdateRepo,
+		UpdateNow:               updateNow,
+		UpdateChannel:           updateChannel,
+		UpdateTag:               strings.TrimSpace(updateTag),
+		RestartOpenrestyNow:     restartOpenrestyNow,
+	}
+}
+
+func collectHeartbeatChanges(previous *model.OpenFlareNode, current *model.OpenFlareNode) map[string]any {
+	if previous == nil || current == nil {
+		return map[string]any{}
+	}
+	changes := make(map[string]any)
+	appendIfChanged := func(key string, before any, after any) {
+		if before != after {
+			changes[key] = after
+		}
+	}
+	appendIfChanged("name", previous.Name, current.Name)
+	appendIfChanged("ip", previous.IP, current.IP)
+	appendIfChanged("version", previous.Version, current.Version)
+	appendIfChanged("ext_version", previous.ExtVersion, current.ExtVersion)
+	appendIfChanged("openresty_status", previous.OpenrestyStatus, current.OpenrestyStatus)
+	appendIfChanged("openresty_message", previous.OpenrestyMessage, current.OpenrestyMessage)
+	appendIfChanged("status", previous.Status, current.Status)
+	appendIfChanged("current_version", previous.CurrentVersion, current.CurrentVersion)
+	appendIfChanged("last_error", previous.LastError, current.LastError)
+	appendIfChanged("update_requested", previous.UpdateRequested, current.UpdateRequested)
+	appendIfChanged("update_channel", previous.UpdateChannel, current.UpdateChannel)
+	appendIfChanged("update_tag", previous.UpdateTag, current.UpdateTag)
+	appendIfChanged("restart_openresty_requested", previous.RestartOpenrestyRequested, current.RestartOpenrestyRequested)
+	if !lastSeenAtEqual(previous.LastSeenAt, current.LastSeenAt) {
+		changes["last_seen_at"] = current.LastSeenAt
+	}
+	return changes
+}
+
+func lastSeenAtEqual(before *time.Time, after *time.Time) bool {
+	if before == nil || after == nil {
+		return before == after
+	}
+	return before.Equal(*after)
+}
+
+func normalizeApplyLogPayload(payload ApplyLogPayload) ApplyLogPayload {
+	payload.NodeID = strings.TrimSpace(payload.NodeID)
+	payload.Version = strings.TrimSpace(payload.Version)
+	payload.Result = strings.ToLower(strings.TrimSpace(payload.Result))
+	payload.Message = truncateForDatabase(strings.TrimSpace(payload.Message), 16000)
+	payload.Checksum = strings.TrimSpace(payload.Checksum)
+	payload.MainConfigChecksum = strings.TrimSpace(payload.MainConfigChecksum)
+	payload.RouteConfigChecksum = strings.TrimSpace(payload.RouteConfigChecksum)
+	return payload
+}
+
+func isUniqueConstraintError(err error) bool {
+	if err == nil {
+		return false
+	}
+	return strings.Contains(strings.ToLower(err.Error()), "unique")
+}
+
+func refreshAccessTokenCache(ctx context.Context, node *model.OpenFlareNode) {
+	if node == nil {
+		return
+	}
+	tokenCache.storeNode(node.AccessToken, cloneNode(node))
+}
+
+func cloneNode(node *model.OpenFlareNode) *model.OpenFlareNode {
+	if node == nil {
+		return nil
+	}
+	cloned := *node
+	return &cloned
+}

Wavelet/internal/apps/openflare/agent/logics.go

@@ -0,0 +1,209 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package agent
+
+import (
+	"context"
+	"errors"
+	"strings"
+	"time"
+
+	"github.com/Rain-kl/Wavelet/internal/apps/openflare/node"
+	"github.com/Rain-kl/Wavelet/internal/db"
+	"github.com/Rain-kl/Wavelet/internal/model"
+	"gorm.io/gorm"
+)
+
+// RegisterWithAccessToken registers an agent on a reserved node token.
+func RegisterWithAccessToken(ctx context.Context, authNode *model.OpenFlareNode, payload NodePayload) (*RegistrationResponse, error) {
+	payload = normalizeNodePayload(payload)
+	if authNode == nil {
+		return nil, errors.New(errNodeNotFound)
+	}
+	if err := validateNodePayload(payload); err != nil {
+		return nil, err
+	}
+	applyNodeRuntime(authNode, payload, true)
+	if err := model.SaveOpenFlareNode(ctx, authNode); err != nil {
+		return nil, err
+	}
+	refreshAccessTokenCache(ctx, authNode)
+	return &RegistrationResponse{
+		NodeID:      authNode.NodeID,
+		AccessToken: authNode.AccessToken,
+		Name:        authNode.Name,
+	}, nil
+}
+
+// RegisterWithDiscovery registers a new node using the global discovery token.
+func RegisterWithDiscovery(ctx context.Context, payload NodePayload) (*RegistrationResponse, error) {
+	payload = normalizeNodePayload(payload)
+	if err := validateNodePayload(payload); err != nil {
+		return nil, err
+	}
+
+	nodeID, err := newServerNodeID()
+	if err != nil {
+		return nil, err
+	}
+	accessToken, err := newRandomToken()
+	if err != nil {
+		return nil, err
+	}
+
+	nodeName := payload.Name
+	if nodeName == "" {
+		nodeName = nodeID
+	}
+
+	record := &model.OpenFlareNode{
+		NodeID:           nodeID,
+		Name:             nodeName,
+		AccessToken:      accessToken,
+		Status:           nodeStatusOnline,
+		NodeType:         "edge_node",
+		CapabilitiesJSON: "[]",
+		UpdateChannel:    releaseChannelStable,
+	}
+	applyNodeRuntime(record, payload, false)
+
+	if err = model.CreateOpenFlareNode(ctx, record); err != nil {
+		if isUniqueConstraintError(err) {
+			return nil, errors.New(errNodeIDConflict)
+		}
+		return nil, err
+	}
+	refreshAccessTokenCache(ctx, record)
+	return &RegistrationResponse{
+		NodeID:      record.NodeID,
+		AccessToken: record.AccessToken,
+		Name:        record.Name,
+	}, nil
+}
+
+// HeartbeatNode updates runtime state and returns agent settings.
+func HeartbeatNode(ctx context.Context, authNode *model.OpenFlareNode, payload NodePayload) (*HeartbeatResponse, error) {
+	if authNode == nil {
+		return nil, errors.New(errNodeNotFound)
+	}
+	payload.NodeID = authNode.NodeID
+	payload = normalizeNodePayload(payload)
+	if err := validateNodePayload(payload); err != nil {
+		return nil, err
+	}
+
+	previous := *authNode
+	updateNow := authNode.UpdateRequested
+	restartOpenrestyNow := authNode.RestartOpenrestyRequested
+	updateChannel := strings.TrimSpace(authNode.UpdateChannel)
+	updateTag := strings.TrimSpace(authNode.UpdateTag)
+
+	applyNodeRuntime(authNode, payload, true)
+	authNode.UpdateRequested = false
+	authNode.UpdateChannel = releaseChannelStable
+	authNode.UpdateTag = ""
+	authNode.RestartOpenrestyRequested = false
+
+	changes := collectHeartbeatChanges(&previous, authNode)
+	if len(changes) > 0 {
+		fields := make([]string, 0, len(changes))
+		for field := range changes {
+			fields = append(fields, field)
+		}
+		if err := model.UpdateOpenFlareNodeFields(ctx, authNode, fields...); err != nil {
+			return nil, err
+		}
+	}
+
+	refreshAccessTokenCache(ctx, authNode)
+
+	activeConfig, err := getActiveConfigMeta(ctx)
+	if err != nil && !isActiveConfigNotFound(err) {
+		return nil, err
+	}
+
+	return &HeartbeatResponse{
+		Node:          authNode,
+		AgentSettings: buildAgentSettings(authNode, updateNow, updateChannel, updateTag, restartOpenrestyNow),
+		ActiveConfig:  activeConfig,
+		WAFIPGroups:   nil,
+	}, nil
+}
+
+// GetActiveConfig returns the active configuration for an agent.
+func GetActiveConfig(ctx context.Context) (*ConfigResponse, error) {
+	config, err := getActiveConfigForAgent(ctx)
+	if err != nil {
+		if isActiveConfigNotFound(err) {
+			return nil, errors.New(errNoActiveConfig)
+		}
+		return nil, err
+	}
+	return config, nil
+}
+
+// SyncWAFIPGroups is a stub until full WAF agent sync is migrated.
+func SyncWAFIPGroups(_ context.Context, _ WAFIPGroupSyncInput) (*WAFIPGroupSyncResult, error) {
+	return &WAFIPGroupSyncResult{Groups: []WAFIPGroup{}}, nil
+}
+
+// ReportApplyLog records an agent apply result.
+func ReportApplyLog(ctx context.Context, payload ApplyLogPayload) (*model.OpenFlareApplyLog, error) {
+	now := time.Now()
+	payload = normalizeApplyLogPayload(payload)
+	if payload.NodeID == "" {
+		return nil, errors.New(errNodeIDRequired)
+	}
+	if payload.Version == "" {
+		return nil, errors.New(errVersionRequired)
+	}
+	if payload.Result != applyResultOK && payload.Result != applyResultWarn && payload.Result != applyResultFailed {
+		return nil, errors.New(errInvalidApplyResult)
+	}
+
+	log := &model.OpenFlareApplyLog{
+		NodeID:              payload.NodeID,
+		Version:             payload.Version,
+		Result:              payload.Result,
+		Message:             payload.Message,
+		Checksum:            payload.Checksum,
+		MainConfigChecksum:  payload.MainConfigChecksum,
+		RouteConfigChecksum: payload.RouteConfigChecksum,
+		SupportFileCount:    payload.SupportFileCount,
+		CreatedAt:           now,
+	}
+
+	conn := db.DB(ctx)
+	if conn == nil {
+		return nil, errors.New("database not initialized")
+	}
+
+	err := conn.Transaction(func(tx *gorm.DB) error {
+		record := &model.OpenFlareNode{}
+		if err := tx.Where("node_id = ?", payload.NodeID).First(record).Error; err != nil {
+			return err
+		}
+		record.Status = nodeStatusOnline
+		record.LastSeenAt = &now
+		if payload.Result == applyResultOK {
+			record.CurrentVersion = payload.Version
+			record.LastError = ""
+		} else {
+			record.LastError = payload.Message
+		}
+		if err := tx.Create(log).Error; err != nil {
+			return err
+		}
+		return tx.Model(record).Select("status", "last_seen_at", "current_version", "last_error").Updates(record).Error
+	})
+	if err != nil {
+		return nil, err
+	}
+	return log, nil
+}
+
+// ValidateDiscoveryToken delegates to the node package discovery token helper.
+func ValidateDiscoveryToken(ctx context.Context, token string) error {
+	return node.ValidateDiscoveryToken(ctx, token)
+}

Wavelet/internal/apps/openflare/agent/middleware.go

@@ -0,0 +1,61 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package agent
+
+import (
+	"strings"
+
+	"github.com/Rain-kl/Wavelet/internal/apps/openflare/compat"
+	"github.com/Rain-kl/Wavelet/internal/model"
+	"github.com/gin-gonic/gin"
+)
+
+const (
+	agentTokenHeader    = "X-Agent-Token"
+	agentNodeContextKey = "agent_node"
+)
+
+// AgentAuth validates X-Agent-Token against of_nodes.access_token.
+func AgentAuth() gin.HandlerFunc {
+	return func(c *gin.Context) {
+		token := strings.TrimSpace(c.GetHeader(agentTokenHeader))
+		node, err := AuthenticateAccessToken(c.Request.Context(), token)
+		if err != nil {
+			compat.Unauthorized(c, errInvalidAgentToken)
+			c.Abort()
+			return
+		}
+		c.Set(agentNodeContextKey, node)
+		c.Next()
+	}
+}
+
+// AgentRegisterAuth accepts either a node access token or the global discovery token.
+func AgentRegisterAuth() gin.HandlerFunc {
+	return func(c *gin.Context) {
+		token := strings.TrimSpace(c.GetHeader(agentTokenHeader))
+		if node, err := AuthenticateAccessToken(c.Request.Context(), token); err == nil {
+			c.Set(agentNodeContextKey, node)
+			c.Next()
+			return
+		}
+		if err := ValidateDiscoveryToken(c.Request.Context(), token); err != nil {
+			compat.Unauthorized(c, errInvalidDiscoveryToken)
+			c.Abort()
+			return
+		}
+		c.Set("discovery_enabled", true)
+		c.Next()
+	}
+}
+
+// AgentNodeFromContext returns the authenticated agent node.
+func AgentNodeFromContext(c *gin.Context) (*model.OpenFlareNode, bool) {
+	value, ok := c.Get(agentNodeContextKey)
+	if !ok {
+		return nil, false
+	}
+	node, ok := value.(*model.OpenFlareNode)
+	return node, ok
+}

Wavelet/internal/apps/openflare/agent/middleware_test.go

@@ -0,0 +1,209 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package agent
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+	"time"
+
+	"github.com/Rain-kl/Wavelet/internal/apps/openflare/compat"
+	"github.com/Rain-kl/Wavelet/internal/apps/openflare/option"
+	"github.com/Rain-kl/Wavelet/internal/db"
+	"github.com/Rain-kl/Wavelet/internal/model"
+	"github.com/gin-gonic/gin"
+	"github.com/glebarez/sqlite"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"gorm.io/gorm"
+)
+
+func setupAgentAuthTestDB(t *testing.T) func() {
+	t.Helper()
+
+	sqliteDB, err := gorm.Open(sqlite.Open(":memory:"), &gorm.Config{
+		DisableForeignKeyConstraintWhenMigrating: true,
+	})
+	require.NoError(t, err)
+	require.NoError(t, sqliteDB.AutoMigrate(
+		&model.OpenFlareNode{},
+		&model.OpenFlareOption{},
+	))
+
+	db.SetDB(sqliteDB)
+	option.ResetInitializationForTest()
+	tokenCache.reset()
+
+	return func() {
+		db.SetDB(nil)
+		option.ResetInitializationForTest()
+		tokenCache.reset()
+	}
+}
+
+func TestAuthenticateAccessToken(t *testing.T) {
+	cleanup := setupAgentAuthTestDB(t)
+	defer cleanup()
+
+	ctx := context.Background()
+	now := time.Now()
+	require.NoError(t, db.DB(ctx).Create(&model.OpenFlareNode{
+		NodeID:      "node-auth-1",
+		Name:        "edge",
+		AccessToken: "valid-agent-token",
+		Status:      nodeStatusOnline,
+		LastSeenAt:  &now,
+		NodeType:    "edge_node",
+	}).Error)
+
+	t.Run("valid token", func(t *testing.T) {
+		node, err := AuthenticateAccessToken(ctx, "valid-agent-token")
+		require.NoError(t, err)
+		assert.Equal(t, "node-auth-1", node.NodeID)
+	})
+
+	t.Run("cached token", func(t *testing.T) {
+		originalLoader := tokenCache.loadNodeByToken
+		t.Cleanup(func() {
+			tokenCache.loadNodeByToken = originalLoader
+		})
+		tokenCache.loadNodeByToken = func(context.Context, string) (*model.OpenFlareNode, error) {
+			t.Fatal("db should not be queried for cached token")
+			return nil, nil
+		}
+		node, err := AuthenticateAccessToken(ctx, "valid-agent-token")
+		require.NoError(t, err)
+		assert.Equal(t, "node-auth-1", node.NodeID)
+	})
+
+	t.Run("missing token", func(t *testing.T) {
+		_, err := AuthenticateAccessToken(ctx, "")
+		require.Error(t, err)
+		assert.Contains(t, err.Error(), errMissingAgentToken)
+	})
+
+	t.Run("invalid token", func(t *testing.T) {
+		_, err := AuthenticateAccessToken(ctx, "invalid-token")
+		require.Error(t, err)
+	})
+}
+
+func TestAgentAuthMiddleware(t *testing.T) {
+	cleanup := setupAgentAuthTestDB(t)
+	defer cleanup()
+
+	ctx := context.Background()
+	now := time.Now()
+	require.NoError(t, db.DB(ctx).Create(&model.OpenFlareNode{
+		NodeID:      "node-mw-1",
+		Name:        "edge",
+		AccessToken: "middleware-token",
+		Status:      nodeStatusOnline,
+		LastSeenAt:  &now,
+		NodeType:    "edge_node",
+	}).Error)
+
+	gin.SetMode(gin.TestMode)
+	router := gin.New()
+	router.GET("/protected", AgentAuth(), func(c *gin.Context) {
+		node, ok := AgentNodeFromContext(c)
+		if !ok {
+			c.Status(http.StatusInternalServerError)
+			return
+		}
+		compat.OK(c, gin.H{"node_id": node.NodeID})
+	})
+
+	t.Run("authorized request", func(t *testing.T) {
+		req := httptest.NewRequest(http.MethodGet, "/protected", nil)
+		req.Header.Set(agentTokenHeader, "middleware-token")
+		resp := httptest.NewRecorder()
+		router.ServeHTTP(resp, req)
+
+		assert.Equal(t, http.StatusOK, resp.Code)
+		var envelope compat.Envelope
+		require.NoError(t, json.Unmarshal(resp.Body.Bytes(), &envelope))
+		assert.True(t, envelope.Success)
+	})
+
+	t.Run("unauthorized request", func(t *testing.T) {
+		req := httptest.NewRequest(http.MethodGet, "/protected", nil)
+		req.Header.Set(agentTokenHeader, "bad-token")
+		resp := httptest.NewRecorder()
+		router.ServeHTTP(resp, req)
+
+		assert.Equal(t, http.StatusUnauthorized, resp.Code)
+	})
+}
+
+func TestAgentRegisterAuthMiddleware(t *testing.T) {
+	cleanup := setupAgentAuthTestDB(t)
+	defer cleanup()
+
+	ctx := context.Background()
+	now := time.Now()
+	require.NoError(t, db.DB(ctx).Create(&model.OpenFlareNode{
+		NodeID:      "node-register-1",
+		Name:        "edge",
+		AccessToken: "existing-node-token",
+		Status:      nodeStatusOnline,
+		LastSeenAt:  &now,
+		NodeType:    "edge_node",
+	}).Error)
+	require.NoError(t, model.UpdateOpenFlareOption(ctx, "AgentDiscoveryToken", "discovery-token"))
+
+	gin.SetMode(gin.TestMode)
+	router := gin.New()
+	router.POST("/register", AgentRegisterAuth(), func(c *gin.Context) {
+		if node, ok := AgentNodeFromContext(c); ok {
+			compat.OK(c, gin.H{"mode": "node", "node_id": node.NodeID})
+			return
+		}
+		if _, ok := c.Get("discovery_enabled"); ok {
+			compat.OK(c, gin.H{"mode": "discovery"})
+			return
+		}
+		c.Status(http.StatusInternalServerError)
+	})
+
+	t.Run("existing node token", func(t *testing.T) {
+		req := httptest.NewRequest(http.MethodPost, "/register", nil)
+		req.Header.Set(agentTokenHeader, "existing-node-token")
+		resp := httptest.NewRecorder()
+		router.ServeHTTP(resp, req)
+
+		assert.Equal(t, http.StatusOK, resp.Code)
+		var envelope compat.Envelope
+		require.NoError(t, json.Unmarshal(resp.Body.Bytes(), &envelope))
+		data, ok := envelope.Data.(map[string]any)
+		require.True(t, ok)
+		assert.Equal(t, "node", data["mode"])
+	})
+
+	t.Run("discovery token", func(t *testing.T) {
+		req := httptest.NewRequest(http.MethodPost, "/register", nil)
+		req.Header.Set(agentTokenHeader, "discovery-token")
+		resp := httptest.NewRecorder()
+		router.ServeHTTP(resp, req)
+
+		assert.Equal(t, http.StatusOK, resp.Code)
+		var envelope compat.Envelope
+		require.NoError(t, json.Unmarshal(resp.Body.Bytes(), &envelope))
+		data, ok := envelope.Data.(map[string]any)
+		require.True(t, ok)
+		assert.Equal(t, "discovery", data["mode"])
+	})
+
+	t.Run("invalid token", func(t *testing.T) {
+		req := httptest.NewRequest(http.MethodPost, "/register", nil)
+		req.Header.Set(agentTokenHeader, "invalid-token")
+		resp := httptest.NewRecorder()
+		router.ServeHTTP(resp, req)
+
+		assert.Equal(t, http.StatusUnauthorized, resp.Code)
+	})
+}

Wavelet/internal/apps/openflare/agent/routers.go

@@ -0,0 +1,161 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package agent
+
+import (
+	"net/http"
+
+	"github.com/Rain-kl/Wavelet/internal/apps/openflare/compat"
+	"github.com/Rain-kl/Wavelet/internal/apps/openflare/websocket"
+	"github.com/gin-gonic/gin"
+)
+
+// RegisterRoutes mounts agent API routes under /agent.
+func RegisterRoutes(apiGroup *gin.RouterGroup) {
+	agentRoute := apiGroup.Group("/agent")
+	{
+		discoveryRoute := agentRoute.Group("/")
+		discoveryRoute.Use(AgentRegisterAuth())
+		{
+			discoveryRoute.POST("/nodes/register", RegisterHandler)
+		}
+
+		authorizedRoute := agentRoute.Group("/")
+		authorizedRoute.Use(AgentAuth())
+		{
+			authorizedRoute.GET("/ws", AgentWebSocketHandler)
+			authorizedRoute.POST("/nodes/heartbeat", HeartbeatHandler)
+			authorizedRoute.GET("/config-versions/active", GetActiveConfigHandler)
+			authorizedRoute.GET("/pages/deployments/:deployment_id/package", DownloadPagesPackageHandler)
+			authorizedRoute.POST("/waf/ip-groups/sync", SyncWAFIPGroupsHandler)
+			authorizedRoute.POST("/apply-logs", ReportApplyLogHandler)
+		}
+	}
+}
+
+// RegisterHandler registers or discovers an agent node.
+func RegisterHandler(c *gin.Context) {
+	var payload NodePayload
+	if !compat.BindJSON(c, &payload) {
+		return
+	}
+	payload.IP = resolveReportedNodeIP(payload.IP, c.Request.RemoteAddr)
+
+	var (
+		result *RegistrationResponse
+		err    error
+	)
+	if authNode, ok := AgentNodeFromContext(c); ok {
+		result, err = RegisterWithAccessToken(c.Request.Context(), authNode, payload)
+	} else {
+		result, err = RegisterWithDiscovery(c.Request.Context(), payload)
+	}
+	if err != nil {
+		compat.Fail(c, err.Error())
+		return
+	}
+	compat.OK(c, result)
+}
+
+// HeartbeatHandler records agent heartbeat state.
+func HeartbeatHandler(c *gin.Context) {
+	var payload NodePayload
+	if !compat.BindJSON(c, &payload) {
+		return
+	}
+	payload.IP = resolveReportedNodeIP(payload.IP, c.Request.RemoteAddr)
+
+	authNode, ok := AgentNodeFromContext(c)
+	if !ok {
+		compat.Unauthorized(c, errInvalidAgentToken)
+		return
+	}
+
+	response, err := HeartbeatNode(c.Request.Context(), authNode, payload)
+	if err != nil {
+		compat.Fail(c, err.Error())
+		return
+	}
+	okWithExtras(c, response.Node, gin.H{
+		"agent_settings": response.AgentSettings,
+		"active_config":  response.ActiveConfig,
+		"waf_ip_groups":  response.WAFIPGroups,
+	})
+}
+
+// GetActiveConfigHandler returns the active configuration version.
+func GetActiveConfigHandler(c *gin.Context) {
+	if _, ok := AgentNodeFromContext(c); !ok {
+		compat.Unauthorized(c, errNodeMissingFromContext)
+		return
+	}
+	config, err := GetActiveConfig(c.Request.Context())
+	if err != nil {
+		compat.Fail(c, err.Error())
+		return
+	}
+	compat.OK(c, config)
+}
+
+// SyncWAFIPGroupsHandler syncs WAF IP groups for an agent (stub).
+func SyncWAFIPGroupsHandler(c *gin.Context) {
+	var input WAFIPGroupSyncInput
+	if !compat.BindJSON(c, &input) {
+		return
+	}
+	result, err := SyncWAFIPGroups(c.Request.Context(), input)
+	if err != nil {
+		compat.Fail(c, err.Error())
+		return
+	}
+	compat.OK(c, result)
+}
+
+// ReportApplyLogHandler records an agent apply log entry.
+func ReportApplyLogHandler(c *gin.Context) {
+	var payload ApplyLogPayload
+	if !compat.BindJSON(c, &payload) {
+		return
+	}
+	if authNode, ok := AgentNodeFromContext(c); ok {
+		payload.NodeID = authNode.NodeID
+	}
+	log, err := ReportApplyLog(c.Request.Context(), payload)
+	if err != nil {
+		compat.Fail(c, err.Error())
+		return
+	}
+	compat.OK(c, log)
+}
+
+// DownloadPagesPackageHandler is a stub until Pages agent packaging is migrated.
+func DownloadPagesPackageHandler(c *gin.Context) {
+	c.JSON(http.StatusNotFound, compat.Envelope{
+		Success: false,
+		Message: errPagesPackageNotFound,
+		Data:    nil,
+	})
+}
+
+// AgentWebSocketHandler upgrades an authenticated agent websocket connection.
+func AgentWebSocketHandler(c *gin.Context) {
+	authNode, ok := AgentNodeFromContext(c)
+	if !ok {
+		compat.Unauthorized(c, errInvalidAgentToken)
+		return
+	}
+	websocket.ServeAgent(c, authNode.NodeID)
+}
+
+func okWithExtras(c *gin.Context, data any, extras gin.H) {
+	payload := gin.H{
+		"success": true,
+		"message": "",
+		"data":    data,
+	}
+	for key, value := range extras {
+		payload[key] = value
+	}
+	c.JSON(http.StatusOK, payload)
+}

Wavelet/internal/apps/openflare/agent/types.go

@@ -0,0 +1,112 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package agent
+
+import (
+	"time"
+
+	"github.com/Rain-kl/Wavelet/internal/model"
+)
+
+const (
+	nodeStatusOnline  = "online"
+	applyResultOK     = "success"
+	applyResultWarn   = "warning"
+	applyResultFailed = "failed"
+)
+
+// NodePayload is the agent register/heartbeat payload.
+type NodePayload struct {
+	NodeID              string            `json:"node_id"`
+	Name                string            `json:"name"`
+	IP                  string            `json:"ip"`
+	Version             string            `json:"version"`
+	ExtVersion          string            `json:"ext_version"`
+	CurrentVersion      string            `json:"current_version"`
+	LastError           string            `json:"last_error"`
+	OpenrestyStatus     string            `json:"openresty_status"`
+	OpenrestyMessage    string            `json:"openresty_message"`
+	WAFIPGroupChecksums map[string]string `json:"waf_ip_group_checksums,omitempty"`
+}
+
+// ApplyLogPayload is the agent apply log report payload.
+type ApplyLogPayload struct {
+	NodeID              string `json:"node_id"`
+	Version             string `json:"version"`
+	Result              string `json:"result"`
+	Message             string `json:"message"`
+	Checksum            string `json:"checksum"`
+	MainConfigChecksum  string `json:"main_config_checksum"`
+	RouteConfigChecksum string `json:"route_config_checksum"`
+	SupportFileCount    int    `json:"support_file_count"`
+}
+
+// RegistrationResponse is returned after agent registration.
+type RegistrationResponse struct {
+	NodeID      string `json:"node_id"`
+	AccessToken string `json:"access_token"`
+	Name        string `json:"name"`
+}
+
+// Settings carries remote agent control flags.
+type Settings struct {
+	HeartbeatInterval       int    `json:"heartbeat_interval"`
+	WebsocketUpgradeEnabled bool   `json:"websocket_upgrade_enabled"`
+	AutoUpdate              bool   `json:"auto_update"`
+	UpdateRepo              string `json:"update_repo"`
+	UpdateNow               bool   `json:"update_now"`
+	UpdateChannel           string `json:"update_channel"`
+	UpdateTag               string `json:"update_tag"`
+	RestartOpenrestyNow     bool   `json:"restart_openresty_now"`
+}
+
+// ActiveConfigMeta summarizes the active configuration version.
+type ActiveConfigMeta struct {
+	Version  string `json:"version"`
+	Checksum string `json:"checksum"`
+}
+
+// SupportFile is a configuration support artifact shipped to agents.
+type SupportFile struct {
+	Path    string `json:"path"`
+	Content string `json:"content"`
+}
+
+// ConfigResponse is the full active config payload for agents.
+type ConfigResponse struct {
+	Version          string        `json:"version"`
+	Checksum         string        `json:"checksum"`
+	SourceConfigJSON string        `json:"source_config_json"`
+	SupportFiles     []SupportFile `json:"support_files"`
+	CreatedAt        time.Time     `json:"created_at"`
+}
+
+// WAFIPGroup is a WAF IP group snapshot for agents.
+type WAFIPGroup struct {
+	ID       uint     `json:"id"`
+	Name     string   `json:"name"`
+	Type     string   `json:"type"`
+	Enabled  bool     `json:"enabled"`
+	IPList   []string `json:"ip_list"`
+	Checksum string   `json:"checksum"`
+}
+
+// WAFIPGroupSyncInput requests changed WAF IP groups.
+type WAFIPGroupSyncInput struct {
+	IDs       []uint            `json:"ids"`
+	Checksums map[string]string `json:"checksums"`
+}
+
+// WAFIPGroupSyncResult returns synced WAF IP groups.
+type WAFIPGroupSyncResult struct {
+	Groups []WAFIPGroup `json:"groups"`
+}
+
+// HeartbeatResponse is the heartbeat handler result.
+type HeartbeatResponse struct {
+	Node          *model.OpenFlareNode `json:"node"`
+	AgentSettings *Settings            `json:"agent_settings"`
+	ActiveConfig  *ActiveConfigMeta    `json:"active_config"`
+	WAFIPGroups   []WAFIPGroup         `json:"waf_ip_groups,omitempty"`
+}