fix(agent): make discovery enrollment compatible and idempotent (#53)

* fix(agent): make discovery enrollment compatible and idempotent

* fix(agent): confirm enrollment persistence and document token aliases
This commit is contained in:
ArthurKoba
2026-11-07 16:29:47 +03:00
committed by GitHub
parent 1ca03df0ef
commit 72d67c80f2
30 changed files with 1324 additions and 71 deletions
+15 -13
View File
@@ -4,17 +4,19 @@
package agent
const (
errMissingAgentToken = "缺少 Agent Token" //nolint:gosec // false positive: this is an error message, not hardcoded credentials
errInvalidAgentToken = "无权进行此操作,Agent Token 无效" //nolint:gosec // false positive: this is an error message, not hardcoded credentials
errInvalidDiscoveryToken = "无权进行此操作,注册 Token 无效" //nolint:gosec // false positive: this is an error message, not hardcoded credentials
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 = "节点标识生成冲突,请重试"
errMissingAgentToken = "缺少 Agent Token" //nolint:gosec // false positive: this is an error message, not hardcoded credentials
errInvalidAgentToken = "无权进行此操作,Agent Token 无效" //nolint:gosec // false positive: this is an error message, not hardcoded credentials
errInvalidDiscoveryToken = "无权进行此操作,注册 Token 无效" //nolint:gosec // false positive: this is an error message, not hardcoded credentials
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 = "节点标识生成冲突,请重试"
errRegistrationKeyInvalid = "invalid discovery registration key"
errRegistrationCredentialChanged = "discovery enrollment credential has changed; use the assigned agent token"
)
+24 -7
View File
@@ -5,6 +5,7 @@ package agent
import (
"context"
"crypto/subtle"
"errors"
"strings"
"time"
@@ -41,18 +42,14 @@ func RegisterWithAccessToken(ctx context.Context, authNode *model.OpenFlareNode,
}
// RegisterWithDiscovery registers a new node using the global discovery token.
func RegisterWithDiscovery(ctx context.Context, payload NodePayload) (*RegistrationResponse, error) {
func RegisterWithDiscovery(ctx context.Context, payload NodePayload, registrationKey string) (*RegistrationResponse, error) {
_ = ofgeoip.EnsureRuntimeProvider(ctx)
payload = normalizeNodePayload(payload)
if err := validateNodePayload(payload); err != nil {
return nil, err
}
nodeID, err := newServerNodeID()
if err != nil {
return nil, err
}
accessToken, err := newRandomToken()
nodeID, accessToken, err := newDiscoveryIdentity(registrationKey)
if err != nil {
return nil, err
}
@@ -73,7 +70,15 @@ func RegisterWithDiscovery(ctx context.Context, payload NodePayload) (*Registrat
}
applyNodeRuntime(ctx, record, payload, false)
if err = repository.CreateOpenFlareNode(ctx, record); err != nil {
if registrationKey != "" {
record, err = repository.CreateOrGetOpenFlareDiscoveryNode(ctx, record)
if err == nil && (record.NodeType != "edge_node" || subtle.ConstantTimeCompare([]byte(record.AccessToken), []byte(accessToken)) != 1) {
return nil, errors.New(errRegistrationCredentialChanged)
}
} else {
err = repository.CreateOpenFlareNode(ctx, record)
}
if err != nil {
if isUniqueConstraintError(err) {
return nil, errors.New(errNodeIDConflict)
}
@@ -87,6 +92,18 @@ func RegisterWithDiscovery(ctx context.Context, payload NodePayload) (*Registrat
}, nil
}
func newDiscoveryIdentity(registrationKey string) (string, string, error) {
if registrationKey != "" {
return discoveryIdentity(registrationKey)
}
nodeID, err := newServerNodeID()
if err != nil {
return "", "", err
}
token, err := newRandomToken()
return nodeID, token, err
}
// HeartbeatNode updates runtime state and returns agent settings.
func HeartbeatNode(ctx context.Context, authNode *model.OpenFlareNode, payload NodePayload) (*HeartbeatResponse, error) {
_ = ofgeoip.EnsureRuntimeProvider(ctx)
@@ -0,0 +1,25 @@
// Copyright 2026 Arctel.net
// SPDX-License-Identifier: Apache-2.0
package agent
import (
"crypto/sha256"
"encoding/base64"
"encoding/hex"
"errors"
)
const registrationKeyBytes = 32
// discoveryIdentity derives separate public identity and private credential from a random retry secret.
// Public node IDs cannot be used as registration keys to recover credentials.
func discoveryIdentity(key string) (string, string, error) {
decoded, err := hex.DecodeString(key)
if err != nil || len(decoded) != registrationKeyBytes {
return "", "", errors.New(errRegistrationKeyInvalid)
}
nodeHash := sha256.Sum256(append([]byte("openflare:discovery:node:v1:"), decoded...))
tokenHash := sha256.Sum256(append([]byte("openflare:discovery:token:v1:"), decoded...))
return "node-" + base64.RawURLEncoding.EncodeToString(nodeHash[:]), hex.EncodeToString(tokenHash[:]), nil
}
@@ -0,0 +1,168 @@
// Copyright 2026 Arctel.net
// SPDX-License-Identifier: Apache-2.0
package agent
import (
"context"
"encoding/json"
"net/http"
"net/http/httptest"
"strings"
"sync"
"testing"
"time"
agentclient "github.com/Rain-kl/Wavelet/internal/apps/agent/httpclient"
db "github.com/Rain-kl/Wavelet/internal/infra/persistence"
"github.com/Rain-kl/Wavelet/internal/model"
"github.com/Rain-kl/Wavelet/internal/repository"
"github.com/Rain-kl/Wavelet/internal/shared/response"
"github.com/Rain-kl/Wavelet/pkg/protocol"
)
func TestRegistrationResponseServerClientContract(t *testing.T) {
server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
w.Header().Set("Content-Type", "application/json")
if err := json.NewEncoder(w).Encode(response.OK(RegistrationResponse{NodeID: "node-contract", AccessToken: "issued", Name: "edge"})); err != nil {
t.Error(err)
}
}))
t.Cleanup(server.Close)
client := agentclient.New(server.URL, "discovery", time.Second)
got, err := client.RegisterNode(context.Background(), protocol.RegisterNodeRequest{})
if err != nil {
t.Fatalf("RegisterNode(server response) error = %v", err)
}
if got.NodeID != "node-contract" || got.AccessToken != "issued" || got.Name != "edge" {
t.Errorf("RegisterNode(server response) = %+v, want node-contract/issued/edge", got)
}
data, err := json.Marshal(RegistrationResponse{AccessToken: "issued"})
if err != nil {
t.Fatal(err)
}
var legacy struct {
AccessToken string `json:"access_token"`
}
if err = json.Unmarshal(data, &legacy); err != nil || legacy.AccessToken != "issued" {
t.Errorf("Decode legacy server response = %q, %v; want issued, nil", legacy.AccessToken, err)
}
var documented RegistrationResponseDocs
if err = json.Unmarshal(data, &documented); err != nil {
t.Fatal(err)
}
if documented.AgentToken != "issued" || documented.AccessToken != documented.AgentToken {
t.Error("RegistrationResponseDocs does not describe both emitted token aliases")
}
}
func TestDiscoveryRetriesKeepOneIdentityAndPreserveChanges(t *testing.T) {
t.Cleanup(setupAgentAuthTestDB(t))
ctx := context.Background()
key := strings.Repeat("a1", 32)
payload := NodePayload{IP: "10.0.0.8", Version: "test", Name: "edge"}
first, err := RegisterWithDiscovery(ctx, payload, key)
if err != nil {
t.Fatal(err)
}
record, err := repository.GetOpenFlareNodeByNodeID(ctx, first.NodeID)
if err != nil {
t.Fatal(err)
}
record.Name = "administrator name"
record.UpdateRequested = true
if err = repository.SaveOpenFlareNode(ctx, record); err != nil {
t.Fatal(err)
}
second, err := RegisterWithDiscovery(ctx, payload, key)
if err != nil {
t.Fatal(err)
}
if first.NodeID != second.NodeID || first.AccessToken != second.AccessToken {
t.Errorf("RegisterWithDiscovery(retry) identity = %+v, want original identity", second)
}
record, err = repository.GetOpenFlareNodeByNodeID(ctx, first.NodeID)
if err != nil {
t.Fatal(err)
}
if record.Name != "administrator name" || !record.UpdateRequested {
t.Errorf("RegisterWithDiscovery(retry) overwrote administrator metadata: %+v", record)
}
other, err := RegisterWithDiscovery(ctx, payload, strings.Repeat("b2", 32))
if err != nil {
t.Fatal(err)
}
if other.NodeID == first.NodeID || other.AccessToken == first.AccessToken {
t.Error("RegisterWithDiscovery(distinct key, same host/IP) reused identity")
}
var count int64
if err = db.DB(ctx).Model(&model.OpenFlareNode{}).Count(&count).Error; err != nil {
t.Fatal(err)
}
if count != 2 {
t.Errorf("RegisterWithDiscovery(two keys, retry) node count = %d, want 2", count)
}
}
func TestDiscoveryConcurrentRetriesAndRevokedCredential(t *testing.T) {
t.Cleanup(setupAgentAuthTestDB(t))
ctx := context.Background()
sqlDB, err := db.DB(ctx).DB()
if err != nil {
t.Fatal(err)
}
sqlDB.SetMaxOpenConns(1)
key := strings.Repeat("c3", 32)
payload := NodePayload{IP: "10.0.0.8", Version: "test"}
const attempts = 12
results := make(chan *RegistrationResponse, attempts)
errors := make(chan error, attempts)
var wg sync.WaitGroup
for range attempts {
wg.Go(func() {
result, registrationErr := RegisterWithDiscovery(ctx, payload, key)
results <- result
errors <- registrationErr
})
}
wg.Wait()
close(results)
close(errors)
for registrationErr := range errors {
if registrationErr != nil {
t.Fatalf("Concurrent RegisterWithDiscovery error = %v", registrationErr)
}
}
var first *RegistrationResponse
for result := range results {
if first == nil {
first = result
}
if result.NodeID != first.NodeID || result.AccessToken != first.AccessToken {
t.Error("Concurrent enrollment returned different identities")
}
}
var count int64
if err = db.DB(ctx).Model(&model.OpenFlareNode{}).Count(&count).Error; err != nil {
t.Fatal(err)
}
if count != 1 {
t.Errorf("Concurrent enrollment node count = %d, want 1", count)
}
record, err := repository.GetOpenFlareNodeByNodeID(ctx, first.NodeID)
if err != nil {
t.Fatal(err)
}
record.AccessToken = "rotated-by-administrator"
if err = repository.SaveOpenFlareNode(ctx, record); err != nil {
t.Fatal(err)
}
if result, retryErr := RegisterWithDiscovery(ctx, payload, key); retryErr == nil || result != nil {
t.Errorf("RegisterWithDiscovery(rotated credential) = %+v, %v; want rejection", result, retryErr)
}
for _, invalid := range []string{"short", strings.Repeat("g", 64), first.NodeID} {
if result, retryErr := RegisterWithDiscovery(ctx, payload, invalid); retryErr == nil || result != nil {
t.Errorf("RegisterWithDiscovery(invalid/public key) = %+v, %v; want rejection", result, retryErr)
}
}
}
+6 -5
View File
@@ -22,16 +22,17 @@ import (
// @Accept json
// @Produce json
// @Security AgentTokenAuth
// @Param body body agent.NodePayload true "节点上报数据"
// @Success 200 {object} response.Any{data=agent.RegistrationResponse} "注册成功"
// @Param body body protocol.RegisterNodeRequest true "节点上报数据;registration_key 为首次注册重试凭证"
// @Success 200 {object} response.Any{data=agent.RegistrationResponseDocs} "注册成功"
// @Failure 400 {object} response.Any "参数错误"
// @Failure 401 {object} response.Any "Token 无效"
// @Router /api/v1/agent/nodes/register [post]
func RegisterHandler(c *gin.Context) {
var payload NodePayload
if !apiutil.BindJSON(c, &payload) {
var request protocol.RegisterNodeRequest
if !apiutil.BindJSON(c, &request) {
return
}
payload := request.NodePayload
payload.IP = resolveReportedNodeIP(payload.IP, c.Request.RemoteAddr)
var (
@@ -41,7 +42,7 @@ func RegisterHandler(c *gin.Context) {
if authNode, ok := NodeFromContext(c); ok {
result, err = RegisterWithAccessToken(c.Request.Context(), authNode, payload)
} else {
result, err = RegisterWithDiscovery(c.Request.Context(), payload)
result, err = RegisterWithDiscovery(c.Request.Context(), payload, request.RegistrationKey)
}
if apiutil.AbortBadRequestOnError(c, err) {
return
+7 -2
View File
@@ -7,6 +7,7 @@ import (
"time"
"github.com/Rain-kl/Wavelet/internal/model"
"github.com/Rain-kl/Wavelet/pkg/protocol"
)
const (
@@ -17,9 +18,13 @@ const (
)
// RegistrationResponse is returned after agent registration.
// Server uses access_token; the agent client expects agent_token via RegisterNodeResponse.
type RegistrationResponse struct {
type RegistrationResponse = protocol.RegisterNodeResponse
// RegistrationResponseDocs describes both token aliases emitted by the custom JSON marshaler.
// It is used only by Swagger; the runtime contract remains protocol.RegisterNodeResponse.
type RegistrationResponseDocs struct {
NodeID string `json:"node_id"`
AgentToken string `json:"agent_token"`
AccessToken string `json:"access_token"`
Name string `json:"name"`
}