fix(nodes): make node API tokens write-only (#5613)

* fix(nodes): make node API tokens write-only

* fix(nodes): keep token optional on edit for write-only API tokens

NodeView no longer returns apiToken, so the edit form must consume hasApiToken and not require re-entering the token. Relaxes the form validation on edit, adds a keep-current placeholder, and adds the i18n key to all 13 locales.

internal/web/service/node.go

@@ -336,6 +336,14 @@ func (s *NodeService) GetById(id int) (*model.Node, error) {
 	return n, nil
 }
 
+func (s *NodeService) GetViewById(id int) (*NodeView, error) {
+	n, err := s.GetById(id)
+	if err != nil {
+		return nil, err
+	}
+	return toNodeView(n), nil
+}
+
 // NodeExists reports whether a node with the given id exists on this panel.
 // Used to drop stale, cross-panel node references on inbound import. A Count
 // query distinguishes "no such node" (count 0, no error) from a real DB error.
@@ -424,6 +432,17 @@ func (s *NodeService) Create(n *model.Node) error {
 	return db.Create(n).Error
 }
 
+func (s *NodeService) CreateFromRequest(req *NodeMutationRequest) (*NodeView, error) {
+	if err := req.validateCredentials(true); err != nil {
+		return nil, err
+	}
+	n := req.toNode()
+	if err := s.Create(n); err != nil {
+		return nil, err
+	}
+	return toNodeView(n), nil
+}
+
 func (s *NodeService) Update(id int, in *model.Node) error {
 	if err := s.normalize(in); err != nil {
 		return err
@@ -467,6 +486,110 @@ func (s *NodeService) Update(id int, in *model.Node) error {
 	return nil
 }
 
+func (s *NodeService) UpdateFromRequest(id int, req *NodeMutationRequest) error {
+	if err := req.validateCredentials(false); err != nil {
+		return err
+	}
+	in := req.toNode()
+	if err := s.normalize(in); err != nil {
+		return err
+	}
+	inboundTagsJSON, err := json.Marshal(in.InboundTags)
+	if err != nil {
+		return err
+	}
+	db := database.GetDB()
+	existing := &model.Node{}
+	if err := db.Where("id = ?", id).First(existing).Error; err != nil {
+		return err
+	}
+	apiToken := existing.ApiToken
+	switch {
+	case req.ClearApiToken:
+		apiToken = ""
+	case req.ApiToken != nil:
+		apiToken = *req.ApiToken
+	}
+	if apiToken == "" && in.Enable && in.TlsVerifyMode != "mtls" {
+		return common.NewError("apiToken is required unless mtls is enabled")
+	}
+	updates := map[string]any{
+		"name":                  in.Name,
+		"remark":                in.Remark,
+		"scheme":                in.Scheme,
+		"address":               in.Address,
+		"port":                  in.Port,
+		"base_path":             in.BasePath,
+		"api_token":             apiToken,
+		"enable":                in.Enable,
+		"allow_private_address": in.AllowPrivateAddress,
+		"tls_verify_mode":       in.TlsVerifyMode,
+		"pinned_cert_sha256":    in.PinnedCertSha256,
+		"inbound_sync_mode":     in.InboundSyncMode,
+		"inbound_tags":          string(inboundTagsJSON),
+		"outbound_tag":          in.OutboundTag,
+	}
+	if err := db.Model(model.Node{}).Where("id = ?", id).Updates(updates).Error; err != nil {
+		return err
+	}
+	if dErr := s.MarkNodeDirty(id); dErr != nil {
+		logger.Warning("mark node dirty after update failed:", dErr)
+	}
+	if mgr := runtime.GetManager(); mgr != nil {
+		mgr.InvalidateNode(id)
+	}
+	return nil
+}
+
+func (s *NodeService) RuntimeNodeFromRequest(id int, req *NodeMutationRequest) (*model.Node, error) {
+	if err := req.validateCredentials(id == 0); err != nil {
+		return nil, err
+	}
+	var n *model.Node
+	if id > 0 {
+		existing, err := s.GetById(id)
+		if err != nil {
+			return nil, err
+		}
+		n = existing
+	} else {
+		n = &model.Node{}
+	}
+	overlay := req.toNode()
+	overlay.Id = id
+	if req.ApiToken == nil {
+		overlay.ApiToken = n.ApiToken
+	}
+	if req.ClearApiToken {
+		overlay.ApiToken = ""
+	}
+	*n = *overlay
+	if err := s.normalize(n); err != nil {
+		return nil, err
+	}
+	if n.ApiToken == "" && n.Enable && n.TlsVerifyMode != "mtls" {
+		return nil, common.NewError("apiToken is required unless mtls is enabled")
+	}
+	return n, nil
+}
+
+func (s *NodeService) NodeFromRequestForCertificate(req *NodeMutationRequest) (*model.Node, error) {
+	if req == nil {
+		return nil, common.NewError("node request is required")
+	}
+	n := req.toNode()
+	if n.Scheme == "" {
+		n.Scheme = "https"
+	}
+	if n.BasePath == "" {
+		n.BasePath = "/"
+	}
+	if err := s.normalize(n); err != nil {
+		return nil, err
+	}
+	return n, nil
+}
+
 func (s *NodeService) GetRemoteInboundOptions(ctx context.Context, n *model.Node) ([]runtime.RemoteInboundOption, error) {
 	if err := s.normalize(n); err != nil {
 		return nil, err

internal/web/service/node_contract.go

@@ -0,0 +1,186 @@
+package service
+
+import (
+	"strings"
+
+	"github.com/mhsanaei/3x-ui/v3/internal/database/model"
+	"github.com/mhsanaei/3x-ui/v3/internal/util/common"
+)
+
+// NodeView is the browser/API read contract for nodes. Credentials are
+// write-only: responses expose only whether a node has a token configured.
+type NodeView struct {
+	Id                  int      `json:"id" example:"1"`
+	Name                string   `json:"name" example:"edge-1"`
+	Remark              string   `json:"remark" example:"Primary edge"`
+	Scheme              string   `json:"scheme" example:"https"`
+	Address             string   `json:"address" example:"node.example.com"`
+	Port                int      `json:"port" example:"2053"`
+	BasePath            string   `json:"basePath" example:"/"`
+	HasApiToken         bool     `json:"hasApiToken" example:"true"`
+	Enable              bool     `json:"enable" example:"true"`
+	AllowPrivateAddress bool     `json:"allowPrivateAddress" example:"false"`
+	TlsVerifyMode       string   `json:"tlsVerifyMode" example:"verify"`
+	PinnedCertSha256    string   `json:"pinnedCertSha256" example:""`
+	InboundSyncMode     string   `json:"inboundSyncMode" example:"all"`
+	InboundTags         []string `json:"inboundTags" example:"[\"in-443-tcp\"]"`
+	OutboundTag         string   `json:"outboundTag" example:"direct"`
+	Guid                string   `json:"guid" example:"node-guid"`
+	Status              string   `json:"status" example:"online"`
+	LastHeartbeat       int64    `json:"lastHeartbeat" example:"1700000000"`
+	LatencyMs           int      `json:"latencyMs" example:"42"`
+	XrayVersion         string   `json:"xrayVersion" example:"25.10.31"`
+	PanelVersion        string   `json:"panelVersion" example:"v3.x.x"`
+	CpuPct              float64  `json:"cpuPct" example:"12.5"`
+	MemPct              float64  `json:"memPct" example:"45.2"`
+	UptimeSecs          uint64   `json:"uptimeSecs" example:"86400"`
+	NetUp               uint64   `json:"netUp" example:"2097152"`
+	NetDown             uint64   `json:"netDown" example:"1048576"`
+	LastError           string   `json:"lastError" example:""`
+	XrayState           string   `json:"xrayState" example:"running"`
+	XrayError           string   `json:"xrayError" example:""`
+	ConfigDirty         bool     `json:"configDirty" example:"false"`
+	ConfigDirtyAt       int64    `json:"configDirtyAt" example:"0"`
+	InboundCount        int      `json:"inboundCount" example:"3"`
+	ClientCount         int      `json:"clientCount" example:"25"`
+	OnlineCount         int      `json:"onlineCount" example:"5"`
+	ActiveCount         int      `json:"activeCount" example:"20"`
+	DisabledCount       int      `json:"disabledCount" example:"2"`
+	DepletedCount       int      `json:"depletedCount" example:"1"`
+	ParentGuid          string   `json:"parentGuid,omitempty" example:""`
+	Transitive          bool     `json:"transitive,omitempty" example:"false"`
+	CreatedAt           int64    `json:"createdAt" example:"1700000000"`
+	UpdatedAt           int64    `json:"updatedAt" example:"1700003600"`
+}
+
+func toNodeView(n *model.Node) *NodeView {
+	if n == nil {
+		return nil
+	}
+	return &NodeView{
+		Id:                  n.Id,
+		Name:                n.Name,
+		Remark:              n.Remark,
+		Scheme:              n.Scheme,
+		Address:             n.Address,
+		Port:                n.Port,
+		BasePath:            n.BasePath,
+		HasApiToken:         n.ApiToken != "",
+		Enable:              n.Enable,
+		AllowPrivateAddress: n.AllowPrivateAddress,
+		TlsVerifyMode:       n.TlsVerifyMode,
+		PinnedCertSha256:    n.PinnedCertSha256,
+		InboundSyncMode:     n.InboundSyncMode,
+		InboundTags:         n.InboundTags,
+		OutboundTag:         n.OutboundTag,
+		Guid:                n.Guid,
+		Status:              n.Status,
+		LastHeartbeat:       n.LastHeartbeat,
+		LatencyMs:           n.LatencyMs,
+		XrayVersion:         n.XrayVersion,
+		PanelVersion:        n.PanelVersion,
+		CpuPct:              n.CpuPct,
+		MemPct:              n.MemPct,
+		UptimeSecs:          n.UptimeSecs,
+		NetUp:               n.NetUp,
+		NetDown:             n.NetDown,
+		LastError:           n.LastError,
+		XrayState:           n.XrayState,
+		XrayError:           n.XrayError,
+		ConfigDirty:         n.ConfigDirty,
+		ConfigDirtyAt:       n.ConfigDirtyAt,
+		InboundCount:        n.InboundCount,
+		ClientCount:         n.ClientCount,
+		OnlineCount:         n.OnlineCount,
+		ActiveCount:         n.ActiveCount,
+		DisabledCount:       n.DisabledCount,
+		DepletedCount:       n.DepletedCount,
+		ParentGuid:          n.ParentGuid,
+		Transitive:          n.Transitive,
+		CreatedAt:           n.CreatedAt,
+		UpdatedAt:           n.UpdatedAt,
+	}
+}
+
+func toNodeViews(nodes []*model.Node) []*NodeView {
+	views := make([]*NodeView, 0, len(nodes))
+	for _, node := range nodes {
+		views = append(views, toNodeView(node))
+	}
+	return views
+}
+
+// NodeMutationRequest is the node write/probe contract. ApiToken is accepted
+// only as input. On update, nil means keep the stored token; replacement and
+// clearing are explicit and mutually exclusive.
+type NodeMutationRequest struct {
+	Id                  int      `json:"id" form:"id"`
+	Name                string   `json:"name" form:"name" validate:"required"`
+	Remark              string   `json:"remark" form:"remark"`
+	Scheme              string   `json:"scheme" form:"scheme" validate:"omitempty,oneof=http https"`
+	Address             string   `json:"address" form:"address" validate:"required"`
+	Port                int      `json:"port" form:"port" validate:"gte=1,lte=65535"`
+	BasePath            string   `json:"basePath" form:"basePath"`
+	ApiToken            *string  `json:"apiToken,omitempty" form:"apiToken"`
+	ClearApiToken       bool     `json:"clearApiToken,omitempty" form:"clearApiToken"`
+	Enable              bool     `json:"enable" form:"enable"`
+	AllowPrivateAddress bool     `json:"allowPrivateAddress" form:"allowPrivateAddress"`
+	TlsVerifyMode       string   `json:"tlsVerifyMode" form:"tlsVerifyMode" validate:"omitempty,oneof=verify skip pin mtls"`
+	PinnedCertSha256    string   `json:"pinnedCertSha256" form:"pinnedCertSha256"`
+	InboundSyncMode     string   `json:"inboundSyncMode" form:"inboundSyncMode" validate:"omitempty,oneof=all selected"`
+	InboundTags         []string `json:"inboundTags" form:"inboundTags"`
+	OutboundTag         string   `json:"outboundTag" form:"outboundTag"`
+}
+
+func (r *NodeMutationRequest) validateCredentials(create bool) error {
+	if r == nil {
+		return common.NewError("node request is required")
+	}
+	if r.ApiToken != nil && r.ClearApiToken {
+		return common.NewError("apiToken and clearApiToken are mutually exclusive")
+	}
+	if r.ApiToken != nil {
+		*r.ApiToken = strings.TrimSpace(*r.ApiToken)
+		if *r.ApiToken == "" {
+			if create {
+				return common.NewError("apiToken is required unless mtls is enabled")
+			}
+			r.ApiToken = nil
+		}
+	}
+	if create {
+		if r.ClearApiToken {
+			return common.NewError("credentials cannot be cleared while creating a node")
+		}
+		if r.ApiToken == nil && r.TlsVerifyMode != "mtls" {
+			return common.NewError("apiToken is required unless mtls is enabled")
+		}
+	}
+	if r.ClearApiToken && r.Enable && r.TlsVerifyMode != "mtls" {
+		return common.NewError("disable the node or enable mtls before clearing its apiToken")
+	}
+	return nil
+}
+
+func (r *NodeMutationRequest) toNode() *model.Node {
+	n := &model.Node{
+		Id:                  r.Id,
+		Name:                r.Name,
+		Remark:              r.Remark,
+		Scheme:              r.Scheme,
+		Address:             r.Address,
+		Port:                r.Port,
+		BasePath:            r.BasePath,
+		Enable:              r.Enable,
+		AllowPrivateAddress: r.AllowPrivateAddress,
+		TlsVerifyMode:       r.TlsVerifyMode,
+		PinnedCertSha256:    r.PinnedCertSha256,
+		InboundSyncMode:     r.InboundSyncMode,
+		InboundTags:         r.InboundTags,
+		OutboundTag:         r.OutboundTag,
+	}
+	if r.ApiToken != nil {
+		n.ApiToken = *r.ApiToken
+	}
+	return n
+}

internal/web/service/node_credentials_writeonly_test.go

@@ -0,0 +1,201 @@
+package service
+
+import (
+	"encoding/json"
+	"strings"
+	"testing"
+
+	"github.com/mhsanaei/3x-ui/v3/internal/database"
+	"github.com/mhsanaei/3x-ui/v3/internal/database/model"
+)
+
+func TestNodeCredentialsNeverMarshal(t *testing.T) {
+	raw, err := json.Marshal(&model.Node{
+		Id:       7,
+		Name:     "node",
+		ApiToken: "plain-secret-token",
+	})
+	if err != nil {
+		t.Fatalf("marshal node: %v", err)
+	}
+	out := string(raw)
+	if strings.Contains(out, "plain-secret-token") || strings.Contains(out, "apiToken") {
+		t.Fatalf("model.Node JSON leaked api token field: %s", out)
+	}
+}
+
+func TestNodeViewExposesOnlyCredentialPresence(t *testing.T) {
+	setupConflictDB(t)
+
+	svc := &NodeService{}
+	reqToken := "write-only-secret"
+	view, err := svc.CreateFromRequest(&NodeMutationRequest{
+		Name:     "node-view",
+		Scheme:   "https",
+		Address:  "127.0.0.1",
+		Port:     2096,
+		ApiToken: &reqToken,
+		Enable:   true,
+	})
+	if err != nil {
+		t.Fatalf("create from request: %v", err)
+	}
+	if !view.HasApiToken {
+		t.Fatal("create view should report credential presence")
+	}
+
+	got, err := svc.GetViewById(view.Id)
+	if err != nil {
+		t.Fatalf("get view: %v", err)
+	}
+	raw, err := json.Marshal(got)
+	if err != nil {
+		t.Fatalf("marshal view: %v", err)
+	}
+	out := string(raw)
+	if !strings.Contains(out, `"hasApiToken":true`) {
+		t.Fatalf("view does not report credential presence: %s", out)
+	}
+	if strings.Contains(out, reqToken) || strings.Contains(out, "apiToken") {
+		t.Fatalf("NodeView leaked plaintext or apiToken key: %s", out)
+	}
+}
+
+func TestNodeCredentialMutationSemantics(t *testing.T) {
+	setupConflictDB(t)
+	svc := &NodeService{}
+
+	initial := "initial-token"
+	view, err := svc.CreateFromRequest(&NodeMutationRequest{
+		Name:     "mut",
+		Scheme:   "https",
+		Address:  "127.0.0.1",
+		Port:     2096,
+		ApiToken: &initial,
+		Enable:   true,
+	})
+	if err != nil {
+		t.Fatalf("create: %v", err)
+	}
+	before := rawStoredNodeToken(t, view.Id)
+	if before != initial {
+		t.Fatalf("stored token = %q, want %q", before, initial)
+	}
+
+	if err := svc.UpdateFromRequest(view.Id, &NodeMutationRequest{
+		Name:    "mut-renamed",
+		Scheme:  "https",
+		Address: "127.0.0.1",
+		Port:    2096,
+		Enable:  true,
+	}); err != nil {
+		t.Fatalf("keep-token update: %v", err)
+	}
+	if after := rawStoredNodeToken(t, view.Id); after != before {
+		t.Fatalf("omitted token should keep existing token: %q -> %q", before, after)
+	}
+
+	blank := " "
+	if err := svc.UpdateFromRequest(view.Id, &NodeMutationRequest{
+		Name:     "mut-blank",
+		Scheme:   "https",
+		Address:  "127.0.0.1",
+		Port:     2096,
+		ApiToken: &blank,
+		Enable:   true,
+	}); err != nil {
+		t.Fatalf("blank apiToken should keep existing token on update: %v", err)
+	}
+	if afterBlank := rawStoredNodeToken(t, view.Id); afterBlank != before {
+		t.Fatalf("blank token should keep existing token: %q -> %q", before, afterBlank)
+	}
+
+	next := "next-token"
+	if err := svc.UpdateFromRequest(view.Id, &NodeMutationRequest{
+		Name:     "mut",
+		Scheme:   "https",
+		Address:  "127.0.0.1",
+		Port:     2096,
+		ApiToken: &next,
+		Enable:   true,
+	}); err != nil {
+		t.Fatalf("replace token: %v", err)
+	}
+	if replaced := rawStoredNodeToken(t, view.Id); replaced != next {
+		t.Fatalf("replace token stored %q, want %q", replaced, next)
+	}
+
+	if err := svc.UpdateFromRequest(view.Id, &NodeMutationRequest{
+		Name:          "mut",
+		Scheme:        "https",
+		Address:       "127.0.0.1",
+		Port:          2096,
+		ClearApiToken: true,
+		Enable:        true,
+	}); err == nil {
+		t.Fatal("enabled non-mtls node must not clear apiToken")
+	}
+	if err := svc.UpdateFromRequest(view.Id, &NodeMutationRequest{
+		Name:          "mut",
+		Scheme:        "https",
+		Address:       "127.0.0.1",
+		Port:          2096,
+		ClearApiToken: true,
+		Enable:        false,
+	}); err != nil {
+		t.Fatalf("clear disabled token: %v", err)
+	}
+	if cleared := rawStoredNodeToken(t, view.Id); cleared != "" {
+		t.Fatalf("clear token left stored value %q", cleared)
+	}
+
+	if _, err := svc.CreateFromRequest(&NodeMutationRequest{
+		Name:          "mtls-only",
+		Scheme:        "https",
+		Address:       "127.0.0.1",
+		Port:          2097,
+		Enable:        true,
+		TlsVerifyMode: "mtls",
+	}); err != nil {
+		t.Fatalf("mtls create without token: %v", err)
+	}
+}
+
+func TestNodeUpdateRequiresTokenWhenNoStoredTokenAndMtlsDisabled(t *testing.T) {
+	setupConflictDB(t)
+	svc := &NodeService{}
+
+	view, err := svc.CreateFromRequest(&NodeMutationRequest{
+		Name:          "mtls-empty",
+		Scheme:        "https",
+		Address:       "127.0.0.1",
+		Port:          2098,
+		Enable:        true,
+		TlsVerifyMode: "mtls",
+	})
+	if err != nil {
+		t.Fatalf("create mtls node: %v", err)
+	}
+	blank := ""
+	if err := svc.UpdateFromRequest(view.Id, &NodeMutationRequest{
+		Name:        "mtls-empty",
+		Scheme:      "https",
+		Address:     "127.0.0.1",
+		Port:        2098,
+		ApiToken:    &blank,
+		Enable:      true,
+		BasePath:    "/",
+		OutboundTag: "",
+	}); err == nil {
+		t.Fatal("enabled non-mtls node without stored token must be rejected")
+	}
+}
+
+func rawStoredNodeToken(t *testing.T, id int) string {
+	t.Helper()
+	var n model.Node
+	if err := database.GetDB().Select("api_token").Where("id = ?", id).First(&n).Error; err != nil {
+		t.Fatalf("load raw node token: %v", err)
+	}
+	return n.ApiToken
+}

internal/web/service/node_tree.go

@@ -157,6 +157,14 @@ func (s *NodeService) GetNodeTree() ([]*model.Node, error) {
 	return all, nil
 }
 
+func (s *NodeService) GetNodeTreeView() ([]*NodeView, error) {
+	nodes, err := s.GetNodeTree()
+	if err != nil {
+		return nil, err
+	}
+	return toNodeViews(nodes), nil
+}
+
 // recountByGuid recomputes InboundCount/OnlineCount/DepletedCount for every node
 // in the tree, keyed by the GUID that physically hosts each inbound, so a direct
 // node shows only its own inbounds and each transitive node shows its own