merge: fix(openflare) align admin permission model with Wavelet

Merge dmux-2026-06-19-110554; resolve changelog conflict keeping /api/v1/d/*
path migration and new AdminMiddlewares permission model.

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

@@ -6,32 +6,12 @@ package apiutil
 import (
 	"github.com/Rain-kl/Wavelet/internal/apps/admin"
 	"github.com/Rain-kl/Wavelet/internal/apps/oauth"
-	"github.com/Rain-kl/Wavelet/internal/common"
-	"github.com/Rain-kl/Wavelet/internal/common/response"
 	"github.com/gin-gonic/gin"
 )
 
-// AdminRequired ensures the caller is logged in as a Wavelet administrator.
+// AdminMiddlewares returns Wavelet-standard middlewares for OpenFlare console routes.
-func AdminRequired() gin.HandlerFunc {
+// OpenFlare no longer distinguishes Admin vs Root tiers; all management endpoints share
-	return func(c *gin.Context) {
+// the same gate: user.IsAdmin for session users, token_admin for Access Token callers.
-		user, err := oauth.GetUserFromRequest(c)
+func AdminMiddlewares() []gin.HandlerFunc {
-		if err != nil {
+	return []gin.HandlerFunc{oauth.LoginRequired(), admin.LoginAdminRequired()}
-			response.AbortUnauthorized(c, common.UnAuthorized)
-			return
-		}
-		oauth.SetToContext(c, oauth.UserObjKey, user)
-
-		if tokenAuth, _ := oauth.GetFromContext[bool](c, oauth.TokenAuthKey); tokenAuth {
-			tokenAdmin, _ := oauth.GetFromContext[bool](c, oauth.TokenAdminKey)
-			if !tokenAdmin {
-				response.AbortNotFound(c, admin.TokenAdminRequired)
-				return
-			}
-		}
-		if !user.IsAdmin {
-			response.AbortNotFound(c, admin.AdminRequired)
-			return
-		}
-		c.Next()
-	}
 }

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

@@ -0,0 +1,158 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package apiutil
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/Rain-kl/Wavelet/internal/apps/admin"
+	"github.com/Rain-kl/Wavelet/internal/apps/oauth"
+	"github.com/Rain-kl/Wavelet/internal/common/response"
+	"github.com/Rain-kl/Wavelet/internal/config"
+	"github.com/Rain-kl/Wavelet/internal/db"
+	"github.com/Rain-kl/Wavelet/internal/db/idgen"
+	"github.com/Rain-kl/Wavelet/internal/model"
+	"github.com/Rain-kl/Wavelet/internal/testhelper"
+	"github.com/gin-contrib/sessions"
+	"github.com/gin-contrib/sessions/cookie"
+	"github.com/gin-gonic/gin"
+	"github.com/glebarez/sqlite"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"gorm.io/gorm"
+)
+
+func setupAdminMiddlewareTest(t *testing.T) (*gin.Engine, *gorm.DB, func()) {
+	t.Helper()
+
+	dbConn, err := gorm.Open(sqlite.Open(":memory:"), &gorm.Config{
+		DisableForeignKeyConstraintWhenMigrating: true,
+	})
+	require.NoError(t, err)
+	require.NoError(t, dbConn.AutoMigrate(&model.User{}, &model.AccessToken{}))
+	db.SetDB(dbConn)
+
+	sessionCookieName := "test_admin_middleware_session"
+	if config.Config.App.SessionCookieName != "" {
+		sessionCookieName = config.Config.App.SessionCookieName
+	}
+	store := cookie.NewStore([]byte("test_admin_middleware_session_secret"))
+	store.Options(oauth.GetSessionOptions(3600))
+	engine := testhelper.NewTestGinEngine(sessions.Sessions(sessionCookieName, store))
+	protected := engine.Group("/protected", AdminMiddlewares()...)
+	protected.GET("", func(c *gin.Context) {
+		c.JSON(http.StatusOK, response.OK(gin.H{"ok": true}))
+	})
+
+	cleanup := func() {
+		db.SetDB(nil)
+	}
+
+	return engine, dbConn, cleanup
+}
+
+func seedUser(t *testing.T, dbConn *gorm.DB, username string, isAdmin bool) *model.User {
+	t.Helper()
+
+	user := &model.User{
+		ID:       idgen.NextUint64ID(),
+		Username: username,
+		Nickname: username,
+		Email:    username + "@openflare.test",
+		IsActive: true,
+		IsAdmin:  isAdmin,
+	}
+	require.NoError(t, dbConn.Create(user).Error)
+	return user
+}
+
+func seedAccessToken(t *testing.T, dbConn *gorm.DB, user *model.User, isAdmin bool) string {
+	t.Helper()
+
+	token, err := model.GenerateTokenString()
+	require.NoError(t, err)
+	require.NoError(t, dbConn.Create(&model.AccessToken{
+		UserID:      user.ID,
+		Name:        user.Username + "-token",
+		TokenHash:   model.HashToken(token),
+		MaskedToken: model.MaskTokenString(token),
+		IsAdmin:     isAdmin,
+	}).Error)
+	return token
+}
+
+func decodeResponse(t *testing.T, rec *httptest.ResponseRecorder) response.Any {
+	t.Helper()
+
+	var resp response.Any
+	require.NoError(t, json.Unmarshal(rec.Body.Bytes(), &resp))
+	return resp
+}
+
+func TestAdminRequiredUnauthenticated(t *testing.T) {
+	engine, _, cleanup := setupAdminMiddlewareTest(t)
+	defer cleanup()
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/protected", nil)
+	engine.ServeHTTP(rec, req)
+
+	assert.Equal(t, http.StatusUnauthorized, rec.Code)
+	resp := decodeResponse(t, rec)
+	assert.NotEmpty(t, resp.ErrorMsg)
+}
+
+func TestAdminRequiredNonAdminToken(t *testing.T) {
+	engine, dbConn, cleanup := setupAdminMiddlewareTest(t)
+	defer cleanup()
+
+	user := seedUser(t, dbConn, "regular", false)
+	token := seedAccessToken(t, dbConn, user, false)
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/protected", nil)
+	req.Header.Set("X-Access-Token", token)
+	engine.ServeHTTP(rec, req)
+
+	assert.Equal(t, http.StatusNotFound, rec.Code)
+	resp := decodeResponse(t, rec)
+	assert.Equal(t, admin.TokenAdminRequired, resp.ErrorMsg)
+}
+
+func TestAdminRequiredAdminWithoutTokenAdmin(t *testing.T) {
+	engine, dbConn, cleanup := setupAdminMiddlewareTest(t)
+	defer cleanup()
+
+	user := seedUser(t, dbConn, "admin-no-token-admin", true)
+	token := seedAccessToken(t, dbConn, user, false)
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/protected", nil)
+	req.Header.Set("X-Access-Token", token)
+	engine.ServeHTTP(rec, req)
+
+	assert.Equal(t, http.StatusNotFound, rec.Code)
+	resp := decodeResponse(t, rec)
+	assert.Equal(t, admin.TokenAdminRequired, resp.ErrorMsg)
+}
+
+func TestAdminRequiredAdminWithTokenAdmin(t *testing.T) {
+	engine, dbConn, cleanup := setupAdminMiddlewareTest(t)
+	defer cleanup()
+
+	user := seedUser(t, dbConn, "admin", true)
+	token := seedAccessToken(t, dbConn, user, true)
+
+	rec := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/protected", nil)
+	req.Header.Set("X-Access-Token", token)
+	engine.ServeHTTP(rec, req)
+
+	assert.Equal(t, http.StatusOK, rec.Code)
+	resp := decodeResponse(t, rec)
+	assert.Empty(t, resp.ErrorMsg)
+}

Wavelet/internal/apps/openflare/integration/auth_option_test.go

@@ -4,8 +4,10 @@
 package integration
 
 import (
+	"bytes"
 	"context"
 	"net/http"
+	"net/http/httptest"
 	"testing"
 
 	"github.com/Rain-kl/Wavelet/internal/apps/admin"
@@ -120,10 +122,10 @@ func TestGETStatusReturnsSuccessEnvelope(t *testing.T) {
 	assert.NotEmpty(t, status.SystemName)
 }
 
-func TestGETOptionRequiresRootAuth(t *testing.T) {
+func TestGETOptionRequiresAdminAuth(t *testing.T) {
 	dbConn, r := setupAuthOptionIntegration(t)
 	commonToken := seedUserWithAccessToken(t, dbConn, "commonuser", "password123", false)
-	rootToken := seedUserWithAccessToken(t, dbConn, "rootuser", "password123", true)
+	adminToken := seedUserWithAccessToken(t, dbConn, "adminuser", "password123", true)
 
 	t.Run("unauthenticated", func(t *testing.T) {
 		w := performJSONRequest(t, r, http.MethodGet, apiPath("/option/"), nil, nil)
@@ -132,26 +134,42 @@ func TestGETOptionRequiresRootAuth(t *testing.T) {
 		assert.NotEmpty(t, resp.ErrorMsg)
 	})
 
-	t.Run("common user forbidden", func(t *testing.T) {
+	t.Run("non-admin user forbidden", func(t *testing.T) {
 		w := performJSONRequest(t, r, http.MethodGet, apiPath("/option/"), nil, adminAuthHeaders(commonToken))
 		assert.Equal(t, http.StatusNotFound, w.Code)
 		resp := decodeAPIResponse(t, w)
 		assert.Equal(t, admin.TokenAdminRequired, resp.ErrorMsg)
 	})
 
-	t.Run("root user allowed", func(t *testing.T) {
+	t.Run("admin user allowed", func(t *testing.T) {
-		w := performJSONRequest(t, r, http.MethodGet, apiPath("/option/"), nil, adminAuthHeaders(rootToken))
+		w := performJSONRequest(t, r, http.MethodGet, apiPath("/option/"), nil, adminAuthHeaders(adminToken))
 		assert.Equal(t, http.StatusOK, w.Code)
 		requireAPIOK(t, w)
 	})
 }
 
+func TestPOSTOptionUpdateRejectsInvalidParams(t *testing.T) {
+	dbConn, r := setupAuthOptionIntegration(t)
+	adminToken := seedUserWithAccessToken(t, dbConn, "adminuser", "password123", true)
+
+	req := httptest.NewRequest(http.MethodPost, apiPath("/option/update"), bytes.NewReader([]byte("{invalid")))
+	req.Header.Set("Content-Type", "application/json")
+	req.Header.Set("X-Access-Token", adminToken)
+
+	w := httptest.NewRecorder()
+	r.ServeHTTP(w, req)
+
+	assert.Equal(t, http.StatusBadRequest, w.Code)
+	resp := decodeAPIResponse(t, w)
+	assert.NotEmpty(t, resp.ErrorMsg)
+}
+
 func TestGETNodesWithAccessToken(t *testing.T) {
 	dbConn, r := setupAuthOptionIntegration(t)
 	require.NoError(t, dbConn.AutoMigrate(&model.OpenFlareNode{}))
-	rootToken := seedUserWithAccessToken(t, dbConn, "admin", "password123", true)
+	adminToken := seedUserWithAccessToken(t, dbConn, "admin", "password123", true)
 
-	w := performJSONRequest(t, r, http.MethodGet, apiPath("/nodes/"), nil, adminAuthHeaders(rootToken))
+	w := performJSONRequest(t, r, http.MethodGet, apiPath("/nodes/"), nil, adminAuthHeaders(adminToken))
 
 	assert.Equal(t, http.StatusOK, w.Code)
 	requireAPIOK(t, w)
@@ -159,7 +177,7 @@ func TestGETNodesWithAccessToken(t *testing.T) {
 
 func TestOptionHotReloadAfterUpdate(t *testing.T) {
 	dbConn, r := setupAuthOptionIntegration(t)
-	rootToken := seedUserWithAccessToken(t, dbConn, "admin", "password123", true)
+	adminToken := seedUserWithAccessToken(t, dbConn, "admin", "password123", true)
 
 	statusBefore := getStatusSystemName(t, r, nil)
 	assert.NotEmpty(t, statusBefore)
@@ -167,7 +185,7 @@ func TestOptionHotReloadAfterUpdate(t *testing.T) {
 	updateResp := performJSONRequest(t, r, http.MethodPost, apiPath("/option/update"), map[string]string{
 		"key":   "SystemName",
 		"value": "HotReloadIntegration",
-	}, adminAuthHeaders(rootToken))
+	}, adminAuthHeaders(adminToken))
 	assert.Equal(t, http.StatusOK, updateResp.Code)
 	requireAPIOK(t, updateResp)
 

Wavelet/internal/router/v1/openflare/register_apply_log.go

@@ -11,7 +11,7 @@ import (
 
 func registerApplyLogRoutes(apiGroup *gin.RouterGroup) {
 	applyLogRoute := apiGroup.Group("/apply-logs")
-	applyLogRoute.Use(apiutil.AdminRequired())
+	applyLogRoute.Use(apiutil.AdminMiddlewares()...)
 	{
 		apiutil.RegisterCollection(applyLogRoute, "GET", apply_log.GetApplyLogs)
 		applyLogRoute.POST("/cleanup", apply_log.CleanupApplyLogs)

Wavelet/internal/router/v1/openflare/register_config_version.go

@@ -11,7 +11,7 @@ import (
 
 func registerConfigVersionRoutes(apiGroup *gin.RouterGroup) {
 	configVersionGroup := apiGroup.Group("/config-versions")
-	configVersionGroup.Use(apiutil.AdminRequired())
+	configVersionGroup.Use(apiutil.AdminMiddlewares()...)
 	{
 		apiutil.RegisterCollection(configVersionGroup, "GET", config_version.ListConfigVersionsHandler)
 		configVersionGroup.GET("/active", config_version.GetActiveConfigVersionHandler)

Wavelet/internal/router/v1/openflare/register_dashboard.go

@@ -11,7 +11,7 @@ import (
 
 func registerDashboardRoutes(apiGroup *gin.RouterGroup) {
 	dashboardRoute := apiGroup.Group("/dashboard")
-	dashboardRoute.Use(apiutil.AdminRequired())
+	dashboardRoute.Use(apiutil.AdminMiddlewares()...)
 	{
 		dashboardRoute.GET("/overview", dashboard.GetOverviewHandler)
 	}

Wavelet/internal/router/v1/openflare/register_node.go

@@ -11,7 +11,7 @@ import (
 
 func registerNodeRoutes(apiGroup *gin.RouterGroup) {
 	nodeRoute := apiGroup.Group("/nodes")
-	nodeRoute.Use(apiutil.AdminRequired())
+	nodeRoute.Use(apiutil.AdminMiddlewares()...)
 	{
 		nodeRoute.GET("/bootstrap-token", node.GetBootstrapTokenHandler)
 		nodeRoute.POST("/bootstrap-token/rotate", node.RotateBootstrapTokenHandler)

Wavelet/internal/router/v1/openflare/register_observability.go

@@ -11,7 +11,7 @@ import (
 
 func registerObservabilityRoutes(apiGroup *gin.RouterGroup) {
 	accessLogRoute := apiGroup.Group("/access-logs")
-	accessLogRoute.Use(apiutil.AdminRequired())
+	accessLogRoute.Use(apiutil.AdminMiddlewares()...)
 	{
 		apiutil.RegisterCollection(accessLogRoute, "GET", observability.GetAccessLogsHandler)
 		accessLogRoute.GET("/folds", observability.GetFoldedAccessLogsHandler)

Wavelet/internal/router/v1/openflare/register_option.go

@@ -15,7 +15,7 @@ func registerOptionRoutes(apiGroup *gin.RouterGroup) {
 	apiGroup.GET("/about", option.GetAboutHandler)
 
 	optionRoute := apiGroup.Group("/option")
-	optionRoute.Use(apiutil.AdminRequired())
+	optionRoute.Use(apiutil.AdminMiddlewares()...)
 	{
 		apiutil.RegisterCollection(optionRoute, "GET", option.ListOptionsHandler)
 		optionRoute.POST("/update", option.UpdateOptionHandler)
@@ -25,7 +25,7 @@ func registerOptionRoutes(apiGroup *gin.RouterGroup) {
 	}
 
 	uptimeKumaRoute := apiGroup.Group("/uptimekuma")
-	uptimeKumaRoute.Use(apiutil.AdminRequired())
+	uptimeKumaRoute.Use(apiutil.AdminMiddlewares()...)
 	{
 		uptimeKumaRoute.POST("/sync", option.SyncUptimeKumaHandler)
 	}

Wavelet/internal/router/v1/openflare/register_origin.go

@@ -11,7 +11,7 @@ import (
 
 func registerOriginRoutes(apiGroup *gin.RouterGroup) {
 	originRoute := apiGroup.Group("/origins")
-	originRoute.Use(apiutil.AdminRequired())
+	originRoute.Use(apiutil.AdminMiddlewares()...)
 	{
 		apiutil.RegisterCollection(originRoute, "GET", origin.GetOrigins)
 		originRoute.GET("/:id", origin.GetOrigin)

Wavelet/internal/router/v1/openflare/register_pages.go

@@ -11,7 +11,7 @@ import (
 
 func registerPagesRoutes(apiGroup *gin.RouterGroup) {
 	pagesRoute := apiGroup.Group("/pages")
-	pagesRoute.Use(apiutil.AdminRequired())
+	pagesRoute.Use(apiutil.AdminMiddlewares()...)
 	{
 		apiutil.RegisterCollection(pagesRoute, "GET", pages.ListProjectsHandler)
 		pagesRoute.GET("/:id", pages.GetProjectHandler)

Wavelet/internal/router/v1/openflare/register_proxy_route.go

@@ -11,7 +11,7 @@ import (
 
 func registerProxyRouteRoutes(apiGroup *gin.RouterGroup) {
 	proxyRouteGroup := apiGroup.Group("/proxy-routes")
-	proxyRouteGroup.Use(apiutil.AdminRequired())
+	proxyRouteGroup.Use(apiutil.AdminMiddlewares()...)
 	{
 		apiutil.RegisterCollection(proxyRouteGroup, "GET", proxy_route.GetProxyRoutes)
 		proxyRouteGroup.GET("/:id", proxy_route.GetProxyRouteHandler)

Wavelet/internal/router/v1/openflare/register_tls.go

@@ -11,7 +11,7 @@ import (
 
 func registerTLSRoutes(apiGroup *gin.RouterGroup) {
 	managedDomainRoute := apiGroup.Group("/managed-domains")
-	managedDomainRoute.Use(apiutil.AdminRequired())
+	managedDomainRoute.Use(apiutil.AdminMiddlewares()...)
 	{
 		apiutil.RegisterCollection(managedDomainRoute, "GET", tls.GetManagedDomains)
 		managedDomainRoute.GET("/match", tls.MatchManagedDomainCertificateHandler)
@@ -21,7 +21,7 @@ func registerTLSRoutes(apiGroup *gin.RouterGroup) {
 	}
 
 	tlsCertificateRoute := apiGroup.Group("/tls-certificates")
-	tlsCertificateRoute.Use(apiutil.AdminRequired())
+	tlsCertificateRoute.Use(apiutil.AdminMiddlewares()...)
 	{
 		apiutil.RegisterCollection(tlsCertificateRoute, "GET", tls.GetCertificates)
 		tlsCertificateRoute.GET("/:id", tls.GetCertificateDetail)
@@ -37,13 +37,13 @@ func registerTLSRoutes(apiGroup *gin.RouterGroup) {
 	}
 
 	acmeAccountRoute := apiGroup.Group("/acme-accounts")
-	acmeAccountRoute.Use(apiutil.AdminRequired())
+	acmeAccountRoute.Use(apiutil.AdminMiddlewares()...)
 	{
 		acmeAccountRoute.GET("/default", tls.GetDefaultAcmeAccountHandler)
 	}
 
 	dnsAccountRoute := apiGroup.Group("/dns-accounts")
-	dnsAccountRoute.Use(apiutil.AdminRequired())
+	dnsAccountRoute.Use(apiutil.AdminMiddlewares()...)
 	{
 		apiutil.RegisterCollection(dnsAccountRoute, "GET", tls.GetDNSAccounts)
 		apiutil.RegisterCollection(dnsAccountRoute, "POST", tls.CreateDNSAccountHandler)

Wavelet/internal/router/v1/openflare/register_update.go

@@ -11,7 +11,7 @@ import (
 
 func registerUpdateRoutes(apiGroup *gin.RouterGroup) {
 	updateRoute := apiGroup.Group("/update")
-	updateRoute.Use(apiutil.AdminRequired())
+	updateRoute.Use(apiutil.AdminMiddlewares()...)
 	{
 		updateRoute.GET("/latest-release", update.GetLatestReleaseHandler)
 		updateRoute.GET("/logs/ws", update.StreamServerUpgradeLogsHandler)

Wavelet/internal/router/v1/openflare/register_waf.go

@@ -11,7 +11,7 @@ import (
 
 func registerWAFRoutes(apiGroup *gin.RouterGroup) {
 	wafRoute := apiGroup.Group("/waf")
-	wafRoute.Use(apiutil.AdminRequired())
+	wafRoute.Use(apiutil.AdminMiddlewares()...)
 	{
 		wafRoute.GET("/ip-groups", waf.ListIPGroupsHandler)
 		wafRoute.GET("/ip-groups/:id", waf.GetIPGroupHandler)

docs/changelog/index.md

@@ -71,6 +71,7 @@ sidebar: false
 ### 变更
 
 - Wavelet API 路径统一：管理端由 `/api/v1/openflare/*` 调整为 `/api/v1/d/*`；Agent/Relay/Tunnel 协议路由分别迁移至 `/api/v1/agent/*`、`/api/v1/relay/*`、`/api/v1/tunnel/*`（原 `/api/flared/*`）。同步更新 Wavelet 前端服务层与 `openflare-agent`、`openflare-relay`、`openflared` 客户端连接端点。
+- OpenFlare 管理端权限模型对齐 Wavelet：取消旧系统 Admin/Root 三级角色区分，统一以 `user.IsAdmin` 为管理门槛；Access Token 访问敏感接口（Option、Update 等）须 `token_admin=true`；权限不足返回 HTTP 404 + `error_msg`，参数错误返回 HTTP 400 + `error_msg`（`apiutil.AdminMiddlewares` = `oauth.LoginRequired` + `admin.LoginAdminRequired`）。
 - 移除 Wavelet 顶栏 OpenFlare 服务端版本入口按钮；版本升级能力保留在 Admin 设置 OpenFlare 运维 Tab。
 - 将 Wavelet 默认上游仓库调整为 `Rain-kl/OpenFlare`，站点名称、邮件模板、前端默认标题与页脚品牌统一初始化为 OpenFlare；新增 goose 迁移回填既有环境的旧 Wavelet 默认值。
 - Wavelet WAF IP 组列表新增「查看」操作，支持在查看弹窗中浏览当前 IP 并移除单条 IP；自动类型同步裁剪 `ext_ips` 以与 `ip_list` 保持一致。
@@ -82,7 +83,7 @@ sidebar: false
 - OpenFlare 管理端路由注册从 `RegisterCustomRoutes` 移至 `v1.RegisterV1Routes`，API 前缀由 `/api/v1/custom/openflare` 调整为 `/api/v1/openflare`。
 - OpenFlare 管理控制台 API 统一迁移至 `/api/v1/d/*`，响应格式对齐 Wavelet `{error_msg, data}` + `response.Abort*`。
 - 节点协议路由迁移至 `/api/v1/agent|relay|tunnel/*`（`flared` 更名为 `tunnel`）；协议层保留 legacy `{success, message, data}` 信封。
-- 控制台鉴权改为 `apiutil.AdminRequired()`（Session / Access Token）。
+- 控制台鉴权改为 `apiutil.AdminMiddlewares()`（`oauth.LoginRequired` + `admin.LoginAdminRequired`；Session / Access Token）。
 - 前端 OpenFlare Service 层切换为 `OpenFlareBaseService`（`BaseService` + `/api/v1/d/*`）。
 - 为 OpenFlare 管理端 API 补充 Swagger 注解（约 99 个端点）。
 - 移除已无引用的 `internal/apps/openflare/auth/`、`compat/routes.go`。