wavelet init

Wavelet/internal/apps/cap/errs.go

@@ -0,0 +1,10 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+// Package cap 提供人机验证中间件
+package cap
+
+const (
+	errCapTokenMissing          = "验证码验证失败，缺少验证码凭证" //nolint:gosec // false positive: this is an error message, not hardcoded credentials
+	errCapTokenInvalidOrExpired = "验证码校验失败或已过期，请重试" //nolint:gosec // false positive: this is an error message, not hardcoded credentials
+)

Wavelet/internal/apps/cap/manager.go

@@ -0,0 +1,196 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+// Package cap provides CAPTCHA and proof-of-work (PoW) verification services.
+package cap
+
+import (
+	"context"
+	"crypto/sha256"
+	"encoding/hex"
+	"strconv"
+	"strings"
+	"sync"
+	"time"
+
+	"github.com/Rain-kl/Wavelet/internal/config"
+	"github.com/Rain-kl/Wavelet/internal/db"
+	pkgcap "github.com/Rain-kl/Wavelet/pkg/cap"
+)
+
+const (
+	redeemTokenIDLength  = 8  // 兑换 Token ID 字节长度
+	redeemVerTokenLength = 15 // 兑换验证 Token 字节长度
+	tokenPartsCount      = 2  // 兑换 Token 由两部分组成
+	valuePartsCount      = 2  // 存储值由 scope 和过期时间组成
+)
+
+// Manager orchestrates challenge generation and solution validation.
+type Manager struct {
+	secret []byte
+	store  pkgcap.Store
+}
+
+// NewManager creates a new CAPTCHA Manager.
+func NewManager(secret []byte, store pkgcap.Store) *Manager {
+	return &Manager{
+		secret: secret,
+		store:  store,
+	}
+}
+
+// Generate creates a challenge response.
+func (m *Manager) Generate(ctx context.Context, scope string) (*pkgcap.ChallengeResponse, error) {
+	settings, err := CurrentSettings(ctx)
+	if err != nil {
+		return nil, err
+	}
+
+	challengeConfig := pkgcap.ChallengeConfig{
+		Count:      settings.ChallengeCount,
+		Size:       settings.ChallengeSize,
+		Difficulty: settings.ChallengeDifficulty,
+		Expires:    settings.ChallengeTTL,
+	}
+	return pkgcap.GenerateChallenge(m.secret, challengeConfig, scope)
+}
+
+// RedeemResponse is returned to the client on redeem.
+type RedeemResponse struct {
+	Success bool   `json:"success"`
+	Token   string `json:"token,omitempty"`
+	Expires int64  `json:"expires,omitempty"`
+	Error   string `json:"error,omitempty"`
+}
+
+// Redeem verifies PoW solutions and returns a one-time redeem token.
+func (m *Manager) Redeem(ctx context.Context, token string, solutions []int, scope string) (*RedeemResponse, error) {
+	sigHex := pkgcap.JwtSigHex(token)
+	if sigHex == "" {
+		return &RedeemResponse{Success: false, Error: "invalid_token"}, nil
+	}
+
+	nonceKey := "cap:nonce:" + sigHex
+
+	payload, err := pkgcap.VerifyChallengeSolutions(token, solutions, m.secret, scope)
+	if err != nil {
+		return &RedeemResponse{Success: false, Error: err.Error()}, nil //nolint:nilerr // validation errors are returned as response, not system errors
+	}
+
+	now := time.Now().UnixNano() / int64(time.Millisecond)
+	nonceTTL := time.Duration(payload.Expires-now) * time.Millisecond
+	if nonceTTL < time.Second {
+		nonceTTL = time.Second
+	}
+
+	set, err := m.store.SetNX(ctx, nonceKey, "1", nonceTTL)
+	if err != nil {
+		return &RedeemResponse{Success: false, Error: "nonce_store_error"}, err
+	}
+	if !set {
+		return &RedeemResponse{Success: false, Error: "already_redeemed"}, nil
+	}
+
+	settings, err := CurrentSettings(ctx)
+	if err != nil {
+		return &RedeemResponse{Success: false, Error: "settings_load_error"}, err
+	}
+
+	id := pkgcap.RandomHex(redeemTokenIDLength)
+	verToken := pkgcap.RandomHex(redeemVerTokenLength)
+	verHashBytes := sha256.Sum256([]byte(verToken))
+	verHashHex := hex.EncodeToString(verHashBytes[:])
+
+	tokenKey := "cap:token:" + id + ":" + verHashHex
+	tokenExpires := time.Now().Add(settings.TokenTTL)
+	storeVal := strconv.FormatInt(tokenExpires.UnixNano(), 10) + "|" + scope
+
+	if err := m.store.Set(ctx, tokenKey, storeVal, settings.TokenTTL); err != nil {
+		return &RedeemResponse{Success: false, Error: "token_store_error"}, err
+	}
+
+	return &RedeemResponse{
+		Success: true,
+		Token:   id + ":" + verToken,
+		Expires: tokenExpires.UnixNano() / int64(time.Millisecond),
+	}, nil
+}
+
+// VerifyToken validates and consumes the redeem token (single-use).
+func (m *Manager) VerifyToken(ctx context.Context, token string, expectedScope string) (bool, error) {
+	if token == "" {
+		return false, nil
+	}
+	parts := strings.Split(token, ":")
+	if len(parts) != tokenPartsCount {
+		return false, nil
+	}
+	id := parts[0]
+	verToken := parts[1]
+
+	verHashBytes := sha256.Sum256([]byte(verToken))
+	verHashHex := hex.EncodeToString(verHashBytes[:])
+
+	tokenKey := "cap:token:" + id + ":" + verHashHex
+
+	val, exists, err := sGetAndDelete(ctx, m.store, tokenKey)
+	if err != nil {
+		return false, err
+	}
+	if !exists {
+		return false, nil
+	}
+
+	valParts := strings.Split(val, "|")
+	if len(valParts) != valuePartsCount {
+		return false, nil
+	}
+
+	expNano, err := strconv.ParseInt(valParts[0], 10, 64)
+	if err != nil {
+		return false, nil //nolint:nilerr // invalid format is treated as validation failure
+	}
+	tokenScope := valParts[1]
+
+	if expectedScope != "" && tokenScope != expectedScope {
+		return false, nil
+	}
+
+	if time.Now().UnixNano() > expNano {
+		return false, nil
+	}
+
+	return true, nil
+}
+
+func sGetAndDelete(ctx context.Context, store pkgcap.Store, key string) (string, bool, error) {
+	if store == nil {
+		return "", false, nil
+	}
+	return store.GetAndDelete(ctx, key)
+}
+
+var (
+	defaultManager *Manager
+	once           sync.Once
+)
+
+// GetDefaultManager yields the global singleton CAPTCHA manager.
+func GetDefaultManager() *Manager {
+	once.Do(func() {
+		secret := []byte("default-captcha-secret-key-at-least-16-bytes")
+		if config.Config != nil && config.Config.App.SessionSecret != "" {
+			secret = []byte(config.Config.App.SessionSecret)
+		}
+
+		var store pkgcap.Store
+		if config.Config != nil && config.Config.Redis.Enabled && db.Redis != nil {
+			store = pkgcap.NewRedisStore(db.Redis)
+		} else {
+			store = pkgcap.NewMemoryStore(1 * time.Minute)
+		}
+
+		defaultManager = NewManager(secret, store)
+	})
+	return defaultManager
+}

Wavelet/internal/apps/cap/manager_test.go

@@ -0,0 +1,162 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package cap
+
+import (
+	"context"
+	"sync"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	pkgcap "github.com/Rain-kl/Wavelet/pkg/cap"
+)
+
+func installTestManagerSettings(t *testing.T) func() {
+	t.Helper()
+	return InstallTestRuntimeSettings(RuntimeSettings{
+		ChallengeCount:      3,
+		ChallengeSize:       32,
+		ChallengeDifficulty: 3,
+		ChallengeTTL:        5 * time.Second,
+		TokenTTL:            10 * time.Second,
+	})
+}
+
+func TestCapFullFlow(t *testing.T) {
+	cleanup := installTestManagerSettings(t)
+	defer cleanup()
+
+	secret := []byte("a-very-long-secret-key-at-least-16-bytes")
+	store := pkgcap.NewMemoryStore(1 * time.Minute)
+	manager := NewManager(secret, store)
+
+	scope := "test-scope"
+	ctx := context.Background()
+	resp, err := manager.Generate(ctx, scope)
+	if err != nil {
+		t.Fatalf("Generate() error = %v", err)
+	}
+
+	if resp.Challenge.C != 3 {
+		t.Fatalf("Generate().Challenge.C = %d, want %d", resp.Challenge.C, 3)
+	}
+
+	solutions := pkgcap.Solve(resp.Token, resp.Challenge.C, resp.Challenge.S, resp.Challenge.D)
+
+	redeemResp, err := manager.Redeem(ctx, resp.Token, solutions, scope)
+	if err != nil {
+		t.Fatalf("Redeem() error = %v", err)
+	}
+	if !redeemResp.Success {
+		t.Fatalf("Redeem().Success = false, error = %s", redeemResp.Error)
+	}
+	if redeemResp.Token == "" {
+		t.Fatal("Redeem().Token is empty")
+	}
+
+	valid, err := manager.VerifyToken(ctx, redeemResp.Token, scope)
+	if err != nil {
+		t.Fatalf("VerifyToken() error = %v", err)
+	}
+	if !valid {
+		t.Fatal("VerifyToken() = false, want true")
+	}
+
+	validAgain, err := manager.VerifyToken(ctx, redeemResp.Token, scope)
+	if err != nil {
+		t.Fatalf("VerifyToken() second call error = %v", err)
+	}
+	if validAgain {
+		t.Fatal("VerifyToken() second call = true, want false")
+	}
+}
+
+func TestRedeemConcurrentRace(t *testing.T) {
+	const goroutines = 50
+
+	cleanup := installTestManagerSettings(t)
+	defer cleanup()
+
+	secret := []byte("race-test-secret-key-at-least-16-bytes")
+	store := pkgcap.NewMemoryStore(1 * time.Minute)
+	manager := NewManager(secret, store)
+
+	ctx := context.Background()
+	resp, err := manager.Generate(ctx, "login")
+	if err != nil {
+		t.Fatalf("Generate() error = %v", err)
+	}
+	solutions := pkgcap.Solve(resp.Token, resp.Challenge.C, resp.Challenge.S, resp.Challenge.D)
+
+	var (
+		wg      sync.WaitGroup
+		success atomic.Int32
+		barrier = make(chan struct{})
+	)
+
+	for range goroutines {
+		wg.Add(1)
+		go func() {
+			defer wg.Done()
+			<-barrier
+			r, _ := manager.Redeem(ctx, resp.Token, solutions, "login")
+			if r != nil && r.Success {
+				success.Add(1)
+			}
+		}()
+	}
+	close(barrier)
+	wg.Wait()
+
+	if got := success.Load(); got != 1 {
+		t.Fatalf("successful Redeem count = %d, want %d", got, 1)
+	}
+}
+
+func TestVerifyTokenConcurrentRace(t *testing.T) {
+	const goroutines = 50
+
+	cleanup := installTestManagerSettings(t)
+	defer cleanup()
+
+	secret := []byte("race-test-secret-key-at-least-16-bytes")
+	store := pkgcap.NewMemoryStore(1 * time.Minute)
+	manager := NewManager(secret, store)
+
+	ctx := context.Background()
+	resp, err := manager.Generate(ctx, "login")
+	if err != nil {
+		t.Fatalf("Generate() error = %v", err)
+	}
+	solutions := pkgcap.Solve(resp.Token, resp.Challenge.C, resp.Challenge.S, resp.Challenge.D)
+	redeemResp, err := manager.Redeem(ctx, resp.Token, solutions, "login")
+	if err != nil || !redeemResp.Success {
+		t.Fatalf("Redeem() error = %v, resp = %+v", err, redeemResp)
+	}
+
+	var (
+		wg      sync.WaitGroup
+		success atomic.Int32
+		barrier = make(chan struct{})
+	)
+
+	for range goroutines {
+		wg.Add(1)
+		go func() {
+			defer wg.Done()
+			<-barrier
+			ok, _ := manager.VerifyToken(ctx, redeemResp.Token, "login")
+			if ok {
+				success.Add(1)
+			}
+		}()
+	}
+	close(barrier)
+	wg.Wait()
+
+	if got := success.Load(); got != 1 {
+		t.Fatalf("successful VerifyToken count = %d, want %d", got, 1)
+	}
+}

Wavelet/internal/apps/cap/middleware.go

@@ -0,0 +1,34 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package cap
+
+import (
+	"github.com/gin-gonic/gin"
+
+	"github.com/Rain-kl/Wavelet/internal/common/response"
+)
+
+// VerifyMiddleware returns a Gin middleware that checks and consumes the X-Cap-Token header.
+func VerifyMiddleware(mgr *Manager, scope string) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		if !ProtectionEnabled(c.Request.Context()) {
+			c.Next()
+			return
+		}
+
+		token := c.GetHeader("X-Cap-Token")
+		if token == "" {
+			response.AbortUnauthorized(c, errCapTokenMissing)
+			return
+		}
+
+		valid, err := mgr.VerifyToken(c.Request.Context(), token, scope)
+		if err != nil || !valid {
+			response.AbortUnauthorized(c, errCapTokenInvalidOrExpired)
+			return
+		}
+
+		c.Next()
+	}
+}

Wavelet/internal/apps/cap/routers.go

@@ -0,0 +1,94 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package cap
+
+import (
+	"net/http"
+
+	"github.com/gin-gonic/gin"
+)
+
+type challengeRequest struct {
+	Scope string `json:"scope" form:"scope"`
+}
+
+type redeemRequest struct {
+	Token     string `json:"token" binding:"required"`
+	Solutions []int  `json:"solutions" binding:"required"`
+	Scope     string `json:"scope" form:"scope"`
+}
+
+// Challenge 生成 PoW 人机验证难题
+// @Summary 生成人机验证难题
+// @Description 客户端获取 PoW 难题和签名的 JWT Token，并在后台计算。
+// @Tags cap
+// @Accept json
+// @Produce json
+// @Param request body challengeRequest false "可选范围限制参数"
+// @Success 200 {object} cap.ChallengeResponse "成功返回 PoW 难题"
+// @Failure 500 {object} RedeemResponse "内部服务错误"
+// @Router /api/cap/challenge [post]
+func Challenge(c *gin.Context) {
+	var req challengeRequest
+	_ = c.ShouldBind(&req) // 允许不传 body，默认使用 login scope
+
+	if req.Scope == "" {
+		req.Scope = "login"
+	}
+
+	mgr := GetDefaultManager()
+	resp, err := mgr.Generate(c.Request.Context(), req.Scope)
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, RedeemResponse{
+			Success: false,
+			Error:   err.Error(),
+		})
+		return
+	}
+
+	c.JSON(http.StatusOK, resp)
+}
+
+// Redeem 提交 PoW 解答并兑换一次性凭证 Token
+// @Summary 校验人机验证解答
+// @Description 提交 PoW 解答进行核销，成功后返回一次性 X-Cap-Token 凭证
+// @Tags cap
+// @Accept json
+// @Produce json
+// @Param request body redeemRequest true "难题 Token 与解答 solutions 数组"
+// @Success 200 {object} RedeemResponse "核销成功，返回 X-Cap-Token"
+// @Failure 400 {object} RedeemResponse "参数错误或核销失败"
+// @Failure 500 {object} RedeemResponse "内部服务错误"
+// @Router /api/cap/redeem [post]
+func Redeem(c *gin.Context) {
+	var req redeemRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		c.JSON(http.StatusBadRequest, RedeemResponse{
+			Success: false,
+			Error:   "无效的参数",
+		})
+		return
+	}
+
+	if req.Scope == "" {
+		req.Scope = "login"
+	}
+
+	mgr := GetDefaultManager()
+	resp, err := mgr.Redeem(c.Request.Context(), req.Token, req.Solutions, req.Scope)
+	if err != nil {
+		c.JSON(http.StatusInternalServerError, RedeemResponse{
+			Success: false,
+			Error:   err.Error(),
+		})
+		return
+	}
+
+	if !resp.Success {
+		c.JSON(http.StatusBadRequest, resp)
+		return
+	}
+
+	c.JSON(http.StatusOK, resp)
+}

Wavelet/internal/apps/cap/routers_test.go

@@ -0,0 +1,128 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package cap
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/gin-gonic/gin"
+
+	"github.com/Rain-kl/Wavelet/internal/common/response"
+	"github.com/Rain-kl/Wavelet/internal/model"
+	"github.com/Rain-kl/Wavelet/internal/repository"
+	"github.com/Rain-kl/Wavelet/internal/testhelper"
+	pkgcap "github.com/Rain-kl/Wavelet/pkg/cap"
+)
+
+func TestCapEndpointsAndMiddleware(t *testing.T) {
+	sqliteDB, _, cleanup := testhelper.SetupTestEnvironment(t)
+	defer cleanup()
+
+	r := testhelper.NewTestGinEngine()
+
+	// Mount CAPTCHA API endpoints
+	capGroup := r.Group("/api/cap")
+	{
+		capGroup.POST("/challenge", Challenge)
+		capGroup.POST("/redeem", Redeem)
+	}
+
+	r.POST("/api/v1/user/login", VerifyMiddleware(GetDefaultManager(), "login"), func(c *gin.Context) {
+		c.JSON(http.StatusOK, response.OK("login success"))
+	})
+
+	// 1. Test challenge generation
+	w := httptest.NewRecorder()
+	req, _ := http.NewRequest("POST", "/api/cap/challenge", nil)
+	r.ServeHTTP(w, req)
+
+	if w.Code != http.StatusOK {
+		t.Fatalf("expected 200 OK, got %d. Body: %s", w.Code, w.Body.String())
+	}
+
+	var challengeResp pkgcap.ChallengeResponse
+	if err := json.Unmarshal(w.Body.Bytes(), &challengeResp); err != nil {
+		t.Fatalf("failed to unmarshal challenge response: %v", err)
+	}
+
+	if challengeResp.Token == "" {
+		t.Fatalf("expected token in challenge response")
+	}
+
+	// 2. Test login with CAPTCHA disabled (should pass)
+	w = httptest.NewRecorder()
+	req, _ = http.NewRequest("POST", "/api/v1/user/login", nil)
+	r.ServeHTTP(w, req)
+	if w.Code != http.StatusOK {
+		t.Fatalf("expected 200 OK when CAPTCHA is disabled, got %d. Body: %s", w.Code, w.Body.String())
+	}
+
+	// 3. Enable CAPTCHA in DB and invalidate runtime snapshot
+	err := sqliteDB.Model(&model.SystemConfig{}).Where("key = ?", model.ConfigKeyCapLoginEnabled).Update("value", "true").Error
+	if err != nil {
+		t.Fatalf("failed to enable cap_login_enabled in DB: %v", err)
+	}
+	if err := repository.InvalidateSystemConfigCache(context.Background(), model.ConfigKeyCapLoginEnabled); err != nil {
+		t.Fatalf("InvalidateSystemConfigCache() error = %v", err)
+	}
+	InvalidateRuntimeSettings()
+
+	// 4. Test login with CAPTCHA enabled but no header (should be blocked)
+	w = httptest.NewRecorder()
+	req, _ = http.NewRequest("POST", "/api/v1/user/login", nil)
+	r.ServeHTTP(w, req)
+	if w.Code != http.StatusUnauthorized {
+		t.Fatalf("expected 401 Unauthorized, got %d. Body: %s", w.Code, w.Body.String())
+	}
+
+	// 5. Solve the challenge
+	solutions := pkgcap.Solve(challengeResp.Token, challengeResp.Challenge.C, challengeResp.Challenge.S, challengeResp.Challenge.D)
+
+	// 6. Redeem solutions
+	redeemReqPayload := redeemRequest{
+		Token:     challengeResp.Token,
+		Solutions: solutions,
+	}
+	bodyBytes, _ := json.Marshal(redeemReqPayload)
+	w = httptest.NewRecorder()
+	req, _ = http.NewRequest("POST", "/api/cap/redeem", bytes.NewBuffer(bodyBytes))
+	req.Header.Set("Content-Type", "application/json")
+	r.ServeHTTP(w, req)
+
+	if w.Code != http.StatusOK {
+		t.Fatalf("expected 200 OK for redeem, got %d. Body: %s", w.Code, w.Body.String())
+	}
+
+	var redeemResp RedeemResponse
+	if err := json.Unmarshal(w.Body.Bytes(), &redeemResp); err != nil {
+		t.Fatalf("failed to unmarshal redeem response: %v", err)
+	}
+
+	if !redeemResp.Success || redeemResp.Token == "" {
+		t.Fatalf("redeem failed or returned empty token: %+v", redeemResp)
+	}
+
+	// 7. Login with valid redeem token (should pass)
+	w = httptest.NewRecorder()
+	req, _ = http.NewRequest("POST", "/api/v1/user/login", nil)
+	req.Header.Set("X-Cap-Token", redeemResp.Token)
+	r.ServeHTTP(w, req)
+	if w.Code != http.StatusOK {
+		t.Fatalf("expected 200 OK with valid cap token, got %d. Body: %s", w.Code, w.Body.String())
+	}
+
+	// 8. Replay attack: Login with the same redeem token again (should be blocked as it is single-use)
+	w = httptest.NewRecorder()
+	req, _ = http.NewRequest("POST", "/api/v1/user/login", nil)
+	req.Header.Set("X-Cap-Token", redeemResp.Token)
+	r.ServeHTTP(w, req)
+	if w.Code != http.StatusUnauthorized {
+		t.Fatalf("expected 401 Unauthorized on replayed token, got %d. Body: %s", w.Code, w.Body.String())
+	}
+}

Wavelet/internal/apps/cap/runtime_settings.go

@@ -0,0 +1,212 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package cap
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"strconv"
+	"sync"
+	"sync/atomic"
+	"time"
+
+	"golang.org/x/sync/singleflight"
+
+	"github.com/Rain-kl/Wavelet/internal/db"
+	"github.com/Rain-kl/Wavelet/internal/model"
+	"github.com/Rain-kl/Wavelet/internal/repository"
+)
+
+const (
+	defaultChallengeCount      = 1
+	defaultChallengeSize       = 32
+	defaultChallengeDifficulty = 4
+	defaultChallengeTTL        = 10 * time.Minute
+	defaultTokenTTL            = 20 * time.Minute
+)
+
+// RuntimeSettings is the parsed CAPTCHA runtime configuration loaded from system_configs.
+type RuntimeSettings struct {
+	LoginEnabled        bool
+	ChallengeCount      int
+	ChallengeSize       int
+	ChallengeDifficulty int
+	ChallengeTTL        time.Duration
+	TokenTTL            time.Duration
+}
+
+var runtimeConfigKeys = []string{
+	model.ConfigKeyCapLoginEnabled,
+	model.ConfigKeyCapChallengeCount,
+	model.ConfigKeyCapChallengeSize,
+	model.ConfigKeyCapChallengeDifficulty,
+	model.ConfigKeyCapChallengeTTL,
+	model.ConfigKeyCapTokenTTL,
+}
+
+var runtimeConfigKeySet = func() map[string]struct{} {
+	set := make(map[string]struct{}, len(runtimeConfigKeys))
+	for _, key := range runtimeConfigKeys {
+		set[key] = struct{}{}
+	}
+	return set
+}()
+
+type runtimeSettingsStore struct {
+	snapshot     atomic.Pointer[RuntimeSettings]
+	loadGroup    singleflight.Group
+	listenerOnce sync.Once
+}
+
+var settingsStore = &runtimeSettingsStore{}
+
+// IsRuntimeConfigKey reports whether a system config key affects CAPTCHA runtime settings.
+func IsRuntimeConfigKey(key string) bool {
+	_, ok := runtimeConfigKeySet[key]
+	return ok
+}
+
+// CurrentSettings returns the cached CAPTCHA runtime settings snapshot.
+func CurrentSettings(ctx context.Context) (RuntimeSettings, error) {
+	return settingsStore.current(ctx)
+}
+
+// ProtectionEnabled reports whether CAPTCHA verification is required for protected routes.
+func ProtectionEnabled(ctx context.Context) bool {
+	settings, err := CurrentSettings(ctx)
+	if err != nil {
+		return false
+	}
+	return settings.LoginEnabled
+}
+
+// InvalidateRuntimeSettings drops the in-process CAPTCHA settings snapshot.
+func InvalidateRuntimeSettings() {
+	settingsStore.snapshot.Store(nil)
+}
+
+// ResetRuntimeSettingsForTest clears the CAPTCHA runtime snapshot.
+func ResetRuntimeSettingsForTest() {
+	InvalidateRuntimeSettings()
+}
+
+// InstallTestRuntimeSettings installs a fixed snapshot for unit tests.
+func InstallTestRuntimeSettings(settings RuntimeSettings) func() {
+	snapshot := settings
+	settingsStore.snapshot.Store(&snapshot)
+	return InvalidateRuntimeSettings
+}
+
+func (s *runtimeSettingsStore) current(ctx context.Context) (RuntimeSettings, error) {
+	s.ensureInvalidationListener()
+
+	if snapshot := s.snapshot.Load(); snapshot != nil {
+		return *snapshot, nil
+	}
+
+	loaded, err, _ := s.loadGroup.Do("cap-runtime-settings", func() (any, error) {
+		if snapshot := s.snapshot.Load(); snapshot != nil {
+			return *snapshot, nil
+		}
+
+		settings, loadErr := loadRuntimeSettings(ctx)
+		if loadErr != nil {
+			return RuntimeSettings{}, loadErr
+		}
+
+		s.snapshot.Store(&settings)
+		return settings, nil
+	})
+	if err != nil {
+		return RuntimeSettings{}, err
+	}
+
+	settings, ok := loaded.(RuntimeSettings)
+	if !ok {
+		return RuntimeSettings{}, errors.New("cap runtime settings loader returned unexpected type")
+	}
+	return settings, nil
+}
+
+func loadRuntimeSettings(ctx context.Context) (RuntimeSettings, error) {
+	configs, err := repository.ListSystemConfigsByKeys(ctx, runtimeConfigKeys)
+	if err != nil {
+		return RuntimeSettings{}, err
+	}
+	return parseRuntimeSettings(configs), nil
+}
+
+func parseRuntimeSettings(configs map[string]model.SystemConfig) RuntimeSettings {
+	settings := RuntimeSettings{
+		ChallengeCount:      defaultChallengeCount,
+		ChallengeSize:       defaultChallengeSize,
+		ChallengeDifficulty: defaultChallengeDifficulty,
+		ChallengeTTL:        defaultChallengeTTL,
+		TokenTTL:            defaultTokenTTL,
+	}
+
+	if sc, ok := configs[model.ConfigKeyCapLoginEnabled]; ok {
+		if enabled, err := strconv.ParseBool(sc.Value); err == nil {
+			settings.LoginEnabled = enabled
+		}
+	}
+	if sc, ok := configs[model.ConfigKeyCapChallengeCount]; ok {
+		if count, err := strconv.Atoi(sc.Value); err == nil && count > 0 {
+			settings.ChallengeCount = count
+		}
+	}
+	if sc, ok := configs[model.ConfigKeyCapChallengeSize]; ok {
+		if size, err := strconv.Atoi(sc.Value); err == nil && size > 0 {
+			settings.ChallengeSize = size
+		}
+	}
+	if sc, ok := configs[model.ConfigKeyCapChallengeDifficulty]; ok {
+		if difficulty, err := strconv.Atoi(sc.Value); err == nil && difficulty > 0 {
+			settings.ChallengeDifficulty = difficulty
+		}
+	}
+	if sc, ok := configs[model.ConfigKeyCapChallengeTTL]; ok {
+		if ttlSeconds, err := strconv.Atoi(sc.Value); err == nil && ttlSeconds > 0 {
+			settings.ChallengeTTL = time.Duration(ttlSeconds) * time.Second
+		}
+	}
+	if sc, ok := configs[model.ConfigKeyCapTokenTTL]; ok {
+		if ttlSeconds, err := strconv.Atoi(sc.Value); err == nil && ttlSeconds > 0 {
+			settings.TokenTTL = time.Duration(ttlSeconds) * time.Second
+		}
+	}
+
+	return settings
+}
+
+func (s *runtimeSettingsStore) ensureInvalidationListener() {
+	s.listenerOnce.Do(startRuntimeSettingsInvalidationListener)
+}
+
+func startRuntimeSettingsInvalidationListener() {
+	if db.Redis == nil {
+		return
+	}
+
+	go func() {
+		pubsub := db.Redis.Subscribe(context.Background(), repository.SystemConfigInvalidationChannel)
+		defer func() {
+			_ = pubsub.Close()
+		}()
+
+		for msg := range pubsub.Channel() {
+			var payload struct {
+				Key string `json:"key"`
+			}
+			if err := json.Unmarshal([]byte(msg.Payload), &payload); err != nil {
+				InvalidateRuntimeSettings()
+				continue
+			}
+			if payload.Key == "" || payload.Key == "*" || IsRuntimeConfigKey(payload.Key) {
+				InvalidateRuntimeSettings()
+			}
+		}
+	}()
+}

Wavelet/internal/apps/cap/runtime_settings_test.go

@@ -0,0 +1,119 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package cap
+
+import (
+	"context"
+	"testing"
+	"time"
+
+	"github.com/Rain-kl/Wavelet/internal/db"
+	"github.com/Rain-kl/Wavelet/internal/model"
+	"github.com/Rain-kl/Wavelet/internal/repository"
+	"github.com/Rain-kl/Wavelet/internal/testhelper"
+)
+
+func TestCurrentSettingsLoadsSnapshotOnce(t *testing.T) {
+	_, _, cleanup := testhelper.SetupTestEnvironment(t)
+	defer cleanup()
+	ctx := context.Background()
+
+	ResetRuntimeSettingsForTest()
+	repository.ResetSystemConfigRAMCacheForTest()
+
+	first, err := CurrentSettings(ctx)
+	if err != nil {
+		t.Fatalf("CurrentSettings() first error = %v", err)
+	}
+	if first.ChallengeCount != 1 {
+		t.Fatalf("CurrentSettings().ChallengeCount = %d, want %d", first.ChallengeCount, 1)
+	}
+
+	if err := db.DB(ctx).Model(&model.SystemConfig{}).
+		Where("key = ?", model.ConfigKeyCapChallengeCount).
+		Update("value", "4").Error; err != nil {
+		t.Fatalf("Update(cap_challenge_count) error = %v", err)
+	}
+	if err := repository.InvalidateSystemConfigCache(ctx, model.ConfigKeyCapChallengeCount); err != nil {
+		t.Fatalf("InvalidateSystemConfigCache() error = %v", err)
+	}
+	InvalidateRuntimeSettings()
+
+	second, err := CurrentSettings(ctx)
+	if err != nil {
+		t.Fatalf("CurrentSettings() second error = %v", err)
+	}
+	if second.ChallengeCount != 4 {
+		t.Fatalf("CurrentSettings().ChallengeCount = %d, want %d", second.ChallengeCount, 4)
+	}
+}
+
+func TestProtectionEnabledReflectsLoginSwitch(t *testing.T) {
+	_, _, cleanup := testhelper.SetupTestEnvironment(t)
+	defer cleanup()
+	ctx := context.Background()
+
+	ResetRuntimeSettingsForTest()
+
+	if ProtectionEnabled(ctx) {
+		t.Fatal("ProtectionEnabled() = true, want false from seed defaults")
+	}
+
+	if err := db.DB(ctx).Model(&model.SystemConfig{}).
+		Where("key = ?", model.ConfigKeyCapLoginEnabled).
+		Update("value", "true").Error; err != nil {
+		t.Fatalf("Update(cap_login_enabled) error = %v", err)
+	}
+	if err := repository.InvalidateSystemConfigCache(ctx, model.ConfigKeyCapLoginEnabled); err != nil {
+		t.Fatalf("InvalidateSystemConfigCache() error = %v", err)
+	}
+	InvalidateRuntimeSettings()
+
+	if !ProtectionEnabled(ctx) {
+		t.Fatal("ProtectionEnabled() = false, want true after config update")
+	}
+}
+
+func TestParseRuntimeSettingsUsesDefaultsForMissingKeys(t *testing.T) {
+	settings := parseRuntimeSettings(map[string]model.SystemConfig{})
+
+	if settings.ChallengeCount != defaultChallengeCount {
+		t.Fatalf("ChallengeCount = %d, want %d", settings.ChallengeCount, defaultChallengeCount)
+	}
+	if settings.ChallengeTTL != defaultChallengeTTL {
+		t.Fatalf("ChallengeTTL = %s, want %s", settings.ChallengeTTL, defaultChallengeTTL)
+	}
+	if settings.TokenTTL != defaultTokenTTL {
+		t.Fatalf("TokenTTL = %s, want %s", settings.TokenTTL, defaultTokenTTL)
+	}
+}
+
+func TestIsRuntimeConfigKey(t *testing.T) {
+	if !IsRuntimeConfigKey(model.ConfigKeyCapChallengeCount) {
+		t.Fatalf("IsRuntimeConfigKey(%s) = false, want true", model.ConfigKeyCapChallengeCount)
+	}
+	if IsRuntimeConfigKey(model.ConfigKeySiteName) {
+		t.Fatalf("IsRuntimeConfigKey(%s) = true, want false", model.ConfigKeySiteName)
+	}
+}
+
+func TestInstallTestRuntimeSettings(t *testing.T) {
+	cleanup := InstallTestRuntimeSettings(RuntimeSettings{
+		LoginEnabled:   true,
+		ChallengeCount: 2,
+		TokenTTL:       30 * time.Minute,
+	})
+	defer cleanup()
+
+	settings, err := CurrentSettings(context.Background())
+	if err != nil {
+		t.Fatalf("CurrentSettings() error = %v", err)
+	}
+	if !settings.LoginEnabled {
+		t.Fatal("LoginEnabled = false, want true")
+	}
+	if settings.ChallengeCount != 2 {
+		t.Fatalf("ChallengeCount = %d, want %d", settings.ChallengeCount, 2)
+	}
+}

Wavelet/internal/apps/cap/testhelper_hook.go

@@ -0,0 +1,10 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package cap
+
+import "github.com/Rain-kl/Wavelet/internal/testhelper"
+
+func init() {
+	testhelper.RegisterCleanup(ResetRuntimeSettingsForTest)
+}