refactor(layout): consolidate backend codebase into backend/ package and clean root directory

- Moved cmd/, core/, plugins/, pkg/, downstream/, and main.go into backend/ directory
- Batch updated all Go source files to import github.com/Rain-kl/Wavelet/backend/...
- Updated Makefile, scripts/swagger.sh, architecture guards, and platform skills
- Passed all quality gates (100% tests, 0 lint issues, clean build)

backend/plugins/domain/auth/audit.go

@@ -0,0 +1,38 @@
+// Copyright 2025 linux.do
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package auth
+
+import (
+	"context"
+	"encoding/json"
+
+	"github.com/Rain-kl/Wavelet/backend/core/contracts"
+	"github.com/Rain-kl/Wavelet/backend/pkg/logger"
+	"github.com/gin-gonic/gin"
+)
+
+// LogForAudit 将登录鉴权审计日志写入 Logger
+func LogForAudit(ctx context.Context, user *contracts.UserDTO, c *gin.Context) {
+	if user == nil || c == nil {
+		return
+	}
+	auditLog := loginRequiredAuditLog{
+		UserID:     user.ID,
+		Username:   user.Username,
+		ClientIP:   c.ClientIP(),
+		Method:     c.Request.Method,
+		Path:       c.Request.URL.Path,
+		RequestURI: c.Request.RequestURI,
+		UserAgent:  c.Request.UserAgent(),
+		Referer:    c.Request.Referer(),
+	}
+	auditJSON, err := json.Marshal(auditLog)
+	if err != nil {
+		logger.ErrorF(ctx, "[LoginRequiredAudit] marshal failed: %v", err)
+		logger.DebugF(ctx, "[LoginRequiredAudit] %s %d %s", c.ClientIP(), user.ID, user.Username)
+	} else {
+		logger.DebugF(ctx, "[LoginRequiredAudit] %s", auditJSON)
+	}
+}

backend/plugins/domain/auth/auth_source_resolver.go

@@ -0,0 +1,219 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package auth
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"strconv"
+	"strings"
+
+	"github.com/Rain-kl/Wavelet/backend/core/contracts"
+	db "github.com/Rain-kl/Wavelet/backend/plugins/infra/database"
+
+	"github.com/coreos/go-oidc/v3/oidc"
+	"golang.org/x/oauth2"
+)
+
+func isOIDCLoginEnabled(ctx context.Context) bool {
+	var val string
+	if err := db.DB(ctx).Table("w_system_configs").Where("key = ?", "oidc_login_enabled").Pluck("value", &val).Error; err != nil || val == "" {
+		return true
+	}
+	b, err := strconv.ParseBool(val)
+	if err != nil {
+		return true
+	}
+	return b
+}
+
+func resolveAuthSource(ctx context.Context, sourceName string) (*AuthSource, error) {
+	name := strings.TrimSpace(strings.ToLower(sourceName))
+	if name == "" {
+		sources, err := GetActiveAuthSourcesCached(ctx)
+		if err != nil {
+			return nil, err
+		}
+		if len(sources) == 0 {
+			return nil, errors.New(errNoActiveAuthSource)
+		}
+		src, err := GetAuthSourceByNameCached(ctx, sources[0].Name)
+		if err != nil {
+			return nil, err
+		}
+		return src, nil
+	}
+	src, err := GetAuthSourceByNameCached(ctx, name)
+	if err != nil {
+		return nil, err
+	}
+	return src, nil
+}
+
+func activeLoginSources(ctx context.Context) []AuthSourceView {
+	if !isOIDCLoginEnabled(ctx) {
+		return nil
+	}
+
+	dbSources, err := GetActiveAuthSourcesCached(ctx)
+	if err != nil {
+		return nil
+	}
+	sources := make([]AuthSourceView, 0, len(dbSources))
+	for _, source := range dbSources {
+		sources = append(sources, AuthSourceView{
+			ID:                     source.ID,
+			Name:                   source.Name,
+			Type:                   source.Type,
+			DisplayName:            source.DisplayName,
+			IsActive:               source.IsActive,
+			IconURL:                source.IconURL,
+			ClientSecretConfigured: source.ClientSecretConfigured,
+		})
+	}
+	return sources
+}
+
+func getFrontendLoginRedirectURL(ctx context.Context) (string, error) {
+	var val string
+	if err := db.DB(ctx).Table("w_system_configs").Where("key = ?", "server_address").Pluck("value", &val).Error; err != nil || strings.TrimSpace(val) == "" {
+		return "", errors.New(errServerAddressMissing)
+	}
+	return strings.TrimRight(val, "/") + "/login", nil
+}
+
+func buildOAuthConfig(ctx context.Context, source *AuthSource, redirectURL string) (*oauth2.Config, *oidc.IDTokenVerifier, error) {
+	if source == nil {
+		return nil, nil, errors.New(errAuthSourceRequired)
+	}
+
+	if source.OpenIDDiscoveryURL == "" {
+		return nil, nil, errors.New(errDiscoveryURLRequired)
+	}
+
+	// Clean the issuer URL
+	issuer := strings.TrimSuffix(strings.TrimSpace(source.OpenIDDiscoveryURL), "/")
+	issuer = strings.TrimSuffix(issuer, "/.well-known/openid-configuration")
+	issuer = strings.TrimSuffix(issuer, "/.well-known/oauth-authorization-server")
+
+	provider, err := globalOIDCProviderCache.get(ctx, issuer)
+	if err != nil {
+		return nil, nil, err
+	}
+	verifier := provider.Verifier(&oidc.Config{ClientID: source.ClientID})
+	scopes := strings.Fields(source.Scopes)
+	if len(scopes) == 0 {
+		scopes = []string{oidc.ScopeOpenID, "profile", "email"}
+	}
+	if !containsScope(scopes, oidc.ScopeOpenID) {
+		scopes = append([]string{oidc.ScopeOpenID}, scopes...)
+	}
+
+	return &oauth2.Config{
+		ClientID:     source.ClientID,
+		ClientSecret: source.ClientSecret,
+		RedirectURL:  redirectURL,
+		Scopes:       scopes,
+		Endpoint:     provider.Endpoint(),
+	}, verifier, nil
+}
+
+func containsScope(scopes []string, scope string) bool {
+	for _, item := range scopes {
+		if item == scope {
+			return true
+		}
+	}
+	return false
+}
+
+func buildOAuthUserInfo(ctx context.Context, source *AuthSource, code string, nonce string, redirectURL string) (*contracts.OAuthUserInfoDTO, error) {
+	authConfig, verifier, err := buildOAuthConfig(ctx, source, redirectURL)
+	if err != nil {
+		return nil, err
+	}
+
+	token, err := authConfig.Exchange(ctx, code)
+	if err != nil {
+		return nil, err
+	}
+
+	userInfo := &contracts.OAuthUserInfoDTO{Active: true}
+	if verifier != nil {
+		if verifyErr := verifyIDToken(ctx, verifier, token, nonce, userInfo); verifyErr != nil {
+			return nil, verifyErr
+		}
+	}
+
+	if userInfo.Username == "" && userInfo.PreferredUsername != "" {
+		userInfo.Username = userInfo.PreferredUsername
+	}
+	if userInfo.Username == "" && userInfo.Email != "" {
+		userInfo.Username = strings.Split(userInfo.Email, "@")[0]
+	}
+	if userInfo.Username == "" && userInfo.Sub != "" {
+		userInfo.Username = userInfo.Sub
+	}
+	if userInfo.Name == "" {
+		userInfo.Name = userInfo.Username
+	}
+
+	return userInfo, nil
+}
+
+func verifyIDToken(ctx context.Context, verifier *oidc.IDTokenVerifier, token *oauth2.Token, nonce string, userInfo *contracts.OAuthUserInfoDTO) error {
+	rawIDToken, ok := token.Extra("id_token").(string)
+	if !ok {
+		return nil
+	}
+	idToken, verifyErr := verifier.Verify(ctx, rawIDToken)
+	if verifyErr != nil {
+		return fmt.Errorf(errIDTokenVerifyFailedFormat, errIDTokenVerifyFailed, verifyErr)
+	}
+	if nonce != "" && idToken.Nonce != nonce {
+		return errors.New(errNonceMismatch)
+	}
+	if claimsErr := idToken.Claims(userInfo); claimsErr != nil {
+		return claimsErr
+	}
+	return nil
+}
+
+func normalizeOAuthUserInfo(userInfo *contracts.OAuthUserInfoDTO) error {
+	userInfo.Username = strings.TrimSpace(userInfo.Username)
+	userInfo.PreferredUsername = strings.TrimSpace(userInfo.PreferredUsername)
+	userInfo.Email = strings.TrimSpace(userInfo.Email)
+	userInfo.Name = strings.TrimSpace(userInfo.Name)
+	userInfo.AvatarURL = strings.TrimSpace(userInfo.AvatarURL)
+
+	if userInfo.Username == "" && userInfo.PreferredUsername != "" {
+		userInfo.Username = userInfo.PreferredUsername
+	}
+	if userInfo.Username == "" && userInfo.Email != "" {
+		userInfo.Username = strings.Split(userInfo.Email, "@")[0]
+	}
+	if userInfo.Username == "" && userInfo.Sub != "" {
+		userInfo.Username = userInfo.Sub
+	}
+	if userInfo.Username == "" {
+		return errors.New(errUsernameFromSourceFailed)
+	}
+	if userInfo.Name == "" {
+		userInfo.Name = userInfo.Username
+	}
+	if !userInfo.Active {
+		userInfo.Active = true
+	}
+	return nil
+}
+
+func buildCallbackResult(user *contracts.UserDTO, status string) OAuthCallbackResult {
+	result := OAuthCallbackResult{Status: status}
+	if user != nil {
+		info := BuildBasicUserInfo(user, false)
+		result.User = &info
+	}
+	return result
+}

backend/plugins/domain/auth/cache.go

@@ -0,0 +1,259 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package auth
+
+import (
+	"context"
+	"fmt"
+	"strconv"
+	"sync"
+	"time"
+
+	"github.com/Rain-kl/Wavelet/backend/core/contracts"
+	"github.com/Rain-kl/Wavelet/backend/pkg/cache/ram"
+	"github.com/Rain-kl/Wavelet/backend/pkg/util"
+	db "github.com/Rain-kl/Wavelet/backend/plugins/infra/cache"
+)
+
+const (
+	tokenCacheTTL = 5 * time.Minute
+	userCacheTTL  = 5 * time.Minute
+
+	//nolint:gosec // This is a Redis Pub/Sub channel name, not a credential
+	oauthTokenInvalidationChannel = "oauth:token_invalidation"
+	oauthUserInvalidationChannel  = "oauth:user_invalidation"
+)
+
+// CachedToken represents the minimal cached representation of an access token.
+type CachedToken struct {
+	ID      uint64 `json:"id"`
+	UserID  uint64 `json:"user_id"`
+	IsAdmin bool   `json:"is_admin"`
+}
+
+var (
+	tokenRAM = ram.MustNew[string, *CachedToken](ram.Options{MaximumSize: 2048})
+	userRAM  = ram.MustNew[uint64, *contracts.UserDTO](ram.Options{MaximumSize: 2048})
+
+	tokenListenerOnce   sync.Once
+	tokenListenerCtx    context.Context
+	tokenListenerCancel context.CancelFunc
+	tokenListenerDone   chan struct{}
+
+	userListenerOnce   sync.Once
+	userListenerCtx    context.Context
+	userListenerCancel context.CancelFunc
+	userListenerDone   chan struct{}
+)
+
+func tokenCacheKey(tokenHash string) string {
+	return "oauth:token:" + tokenHash
+}
+
+func userCacheKey(userID uint64) string {
+	return fmt.Sprintf("oauth:user:%d", userID)
+}
+
+func ensureTokenCacheListener() {
+	if db.Redis == nil {
+		return
+	}
+	tokenListenerOnce.Do(startTokenCacheInvalidationListener)
+}
+
+func startTokenCacheInvalidationListener() {
+	tokenListenerCtx, tokenListenerCancel = context.WithCancel(context.Background())
+	tokenListenerDone = make(chan struct{})
+
+	redisClient := db.Redis // 捕获当前客户端：goroutine 不读可变全局，避免与测试置空 db.Redis 竞争
+	util.Go(func() {
+		listenerCtx := tokenListenerCtx
+		defer close(tokenListenerDone)
+
+		pubsub := redisClient.Subscribe(listenerCtx, oauthTokenInvalidationChannel)
+		defer func() {
+			_ = pubsub.Close()
+		}()
+
+		util.Go(func() {
+			<-listenerCtx.Done()
+			_ = pubsub.Close()
+		})
+
+		for msg := range pubsub.Channel() {
+			tokenHash := msg.Payload
+			if tokenHash == "" || tokenHash == "*" || tokenHash == "reset" {
+				tokenRAM.InvalidateAll()
+			} else {
+				tokenRAM.Invalidate(tokenHash)
+			}
+		}
+	})
+}
+
+func publishTokenRAMInvalidation(ctx context.Context, tokenHash string) {
+	if db.Redis == nil {
+		return
+	}
+	_ = db.Redis.Publish(ctx, oauthTokenInvalidationChannel, tokenHash).Err()
+}
+
+func ensureUserCacheListener() {
+	if db.Redis == nil {
+		return
+	}
+	userListenerOnce.Do(startUserCacheInvalidationListener)
+}
+
+func startUserCacheInvalidationListener() {
+	userListenerCtx, userListenerCancel = context.WithCancel(context.Background())
+	userListenerDone = make(chan struct{})
+
+	redisClient := db.Redis // 捕获当前客户端：goroutine 不读可变全局，避免与测试置空 db.Redis 竞争
+	util.Go(func() {
+		listenerCtx := userListenerCtx
+		defer close(userListenerDone)
+
+		pubsub := redisClient.Subscribe(listenerCtx, oauthUserInvalidationChannel)
+		defer func() {
+			_ = pubsub.Close()
+		}()
+
+		util.Go(func() {
+			<-listenerCtx.Done()
+			_ = pubsub.Close()
+		})
+
+		for msg := range pubsub.Channel() {
+			userIDStr := msg.Payload
+			if userIDStr == "" || userIDStr == "*" || userIDStr == "reset" {
+				userRAM.InvalidateAll()
+			} else if userID, err := strconv.ParseUint(userIDStr, 10, 64); err == nil {
+				userRAM.Invalidate(userID)
+			}
+		}
+	})
+}
+
+func publishUserRAMInvalidation(ctx context.Context, userID uint64) {
+	if db.Redis == nil {
+		return
+	}
+	_ = db.Redis.Publish(ctx, oauthUserInvalidationChannel, strconv.FormatUint(userID, 10)).Err()
+}
+
+// GetCachedToken 获取缓存的 Token
+func GetCachedToken(ctx context.Context, tokenHash string) (*CachedToken, error) {
+	ensureTokenCacheListener()
+
+	if val, ok := tokenRAM.GetIfPresent(tokenHash); ok {
+		return val, nil
+	}
+
+	if db.Redis != nil {
+		var token CachedToken
+		key := tokenCacheKey(tokenHash)
+		if err := db.GetJSON(ctx, key, &token); err == nil {
+			// Write back to local cache
+			tokenRAM.Set(tokenHash, &token)
+			return &token, nil
+		}
+	}
+	return nil, fmt.Errorf("cache miss")
+}
+
+// SetCachedToken 设置 Token 缓存
+func SetCachedToken(ctx context.Context, tokenHash string, token *CachedToken) {
+	ensureTokenCacheListener()
+
+	tokenRAM.Set(tokenHash, token)
+	if db.Redis != nil {
+		key := tokenCacheKey(tokenHash)
+		_ = db.SetJSON(ctx, key, token, tokenCacheTTL)
+	}
+}
+
+// InvalidateCachedToken 吊销/删除 token 缓存
+func InvalidateCachedToken(ctx context.Context, tokenHash string) {
+	ensureTokenCacheListener()
+
+	tokenRAM.Invalidate(tokenHash)
+	if db.Redis != nil {
+		key := tokenCacheKey(tokenHash)
+		_ = db.Redis.Del(ctx, db.PrefixedKey(key)).Err()
+		publishTokenRAMInvalidation(ctx, tokenHash)
+	}
+}
+
+// GetCachedUser 获取缓存的 UserDTO
+func GetCachedUser(ctx context.Context, userID uint64) (*contracts.UserDTO, error) {
+	ensureUserCacheListener()
+
+	if val, ok := userRAM.GetIfPresent(userID); ok {
+		return val, nil
+	}
+
+	if db.Redis != nil {
+		var u contracts.UserDTO
+		key := userCacheKey(userID)
+		if err := db.GetJSON(ctx, key, &u); err == nil {
+			// Write back to local cache
+			userRAM.Set(userID, &u)
+			return &u, nil
+		}
+	}
+	return nil, fmt.Errorf("cache miss")
+}
+
+// SetCachedUser 设置 UserDTO 缓存
+func SetCachedUser(ctx context.Context, userID uint64, u *contracts.UserDTO) {
+	ensureUserCacheListener()
+
+	userRAM.Set(userID, u)
+	if db.Redis != nil {
+		key := userCacheKey(userID)
+		_ = db.SetJSON(ctx, key, u, userCacheTTL)
+	}
+}
+
+// InvalidateCachedUser 吊销/失效 UserDTO 缓存
+func InvalidateCachedUser(ctx context.Context, userID uint64) {
+	ensureUserCacheListener()
+
+	userRAM.Invalidate(userID)
+	if db.Redis != nil {
+		key := userCacheKey(userID)
+		_ = db.Redis.Del(ctx, db.PrefixedKey(key)).Err()
+		publishUserRAMInvalidation(ctx, userID)
+	}
+}
+
+// StopAuthCacheListener stops both token and user Redis Pub/Sub subscription listeners and resets the sync.Once guards.
+func StopAuthCacheListener() {
+	if tokenListenerCancel != nil {
+		tokenListenerCancel()
+		if tokenListenerDone != nil {
+			<-tokenListenerDone
+		}
+		tokenListenerCancel = nil
+		tokenListenerDone = nil
+	}
+	tokenListenerOnce = sync.Once{}
+
+	if userListenerCancel != nil {
+		userListenerCancel()
+		if userListenerDone != nil {
+			<-userListenerDone
+		}
+		userListenerCancel = nil
+		userListenerDone = nil
+	}
+	userListenerOnce = sync.Once{}
+}
+
+// ResetAuthRAMCacheForTest clears only the process-local RAM cache.
+func ResetAuthRAMCacheForTest() {
+	tokenRAM.InvalidateAll()
+	userRAM.InvalidateAll()
+}

backend/plugins/domain/auth/cache_test.go

@@ -0,0 +1,124 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package auth_test
+
+import (
+	"context"
+	"testing"
+
+	"github.com/alicebob/miniredis/v2"
+	"github.com/redis/go-redis/v9"
+	"github.com/redis/go-redis/v9/maintnotifications"
+
+	"github.com/Rain-kl/Wavelet/backend/core/contracts"
+	"github.com/Rain-kl/Wavelet/backend/plugins/domain/auth"
+	db "github.com/Rain-kl/Wavelet/backend/plugins/infra/cache"
+)
+
+func setupOauthCacheTest(t *testing.T) (*miniredis.Miniredis, func()) {
+	t.Helper()
+
+	miniRedis, err := miniredis.Run()
+	if err != nil {
+		t.Fatalf("failed to start miniredis: %v", err)
+	}
+
+	db.Redis = redis.NewClient(&redis.Options{
+		Addr: miniRedis.Addr(),
+		MaintNotificationsConfig: &maintnotifications.Config{
+			Mode: maintnotifications.ModeDisabled,
+		},
+	})
+
+	auth.ResetAuthRAMCacheForTest()
+
+	cleanup := func() {
+		auth.StopAuthCacheListener()
+		auth.ResetAuthRAMCacheForTest()
+		_ = db.Redis.Close()
+		miniRedis.Close()
+		db.Redis = nil
+	}
+	return miniRedis, cleanup
+}
+
+func TestTokenCache_GetSetInvalidate(t *testing.T) {
+	_, cleanup := setupOauthCacheTest(t)
+	defer cleanup()
+	ctx := context.Background()
+
+	tokenHash := "test-token-hash"
+	token := &auth.CachedToken{
+		ID:      123,
+		UserID:  456,
+		IsAdmin: true,
+	}
+
+	// 1. Get from empty cache -> miss
+	_, err := auth.GetCachedToken(ctx, tokenHash)
+	if err == nil {
+		t.Fatal("expected cache miss for un-cached token")
+	}
+
+	// 2. Set to cache
+	auth.SetCachedToken(ctx, tokenHash, token)
+
+	// 3. Get from cache -> hit
+	cached, err := auth.GetCachedToken(ctx, tokenHash)
+	if err != nil {
+		t.Fatalf("GetCachedToken() failed: %v", err)
+	}
+	if cached.ID != token.ID || cached.UserID != token.UserID || cached.IsAdmin != token.IsAdmin {
+		t.Fatalf("expected cached token %+v, got %+v", token, cached)
+	}
+
+	// 4. Invalidate cache
+	auth.InvalidateCachedToken(ctx, tokenHash)
+
+	// 5. Get from cache -> miss
+	_, err = auth.GetCachedToken(ctx, tokenHash)
+	if err == nil {
+		t.Fatal("expected cache miss after invalidation")
+	}
+}
+
+func TestUserCache_GetSetInvalidate(t *testing.T) {
+	_, cleanup := setupOauthCacheTest(t)
+	defer cleanup()
+	ctx := context.Background()
+
+	userID := uint64(789)
+	user := &contracts.UserDTO{
+		ID:       userID,
+		Username: "testuser",
+		Email:    "test@example.com",
+	}
+
+	// 1. Get from empty cache -> miss
+	_, err := auth.GetCachedUser(ctx, userID)
+	if err == nil {
+		t.Fatal("expected cache miss for un-cached user")
+	}
+
+	// 2. Set to cache
+	auth.SetCachedUser(ctx, userID, user)
+
+	// 3. Get from cache -> hit
+	cached, err := auth.GetCachedUser(ctx, userID)
+	if err != nil {
+		t.Fatalf("GetCachedUser() failed: %v", err)
+	}
+	if cached.ID != user.ID || cached.Username != user.Username {
+		t.Fatalf("expected cached user %+v, got %+v", user, cached)
+	}
+
+	// 4. Invalidate cache
+	auth.InvalidateCachedUser(ctx, userID)
+
+	// 5. Get from cache -> miss
+	_, err = auth.GetCachedUser(ctx, userID)
+	if err == nil {
+		t.Fatal("expected cache miss after invalidation")
+	}
+}

backend/plugins/domain/auth/constants.go

@@ -0,0 +1,40 @@
+// Copyright 2025 linux.do
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package auth
+
+import (
+	"time"
+)
+
+// Session and Context Keys
+const (
+	UserNameKey     = "username"
+	UserIDKey       = "user_id"
+	UserObjKey      = "user_obj"
+	TokenAuthKey    = "token_auth"          // 标记当前请求是否通过 Access Token 鉴权
+	TokenAdminKey   = "token_admin"         // Access Token 本身是否具有管理员权限
+	SessionTokenKey = "oauth_session_token" //nolint:gosec // false positive: this is a session key, not hardcoded credentials
+	PasswordHashKey = "password_hash"
+	SystemUsername  = "system"
+)
+
+// OAuth State Cache Keys and Expirations
+const (
+	OAuthStateCacheKeyFormat     = "oauth:state:%s"
+	OAuthStateCacheKeyExpiration = 10 * time.Minute
+	oauthStateLimitKeyFormat     = "oauth:state:limit:%s"
+	oauthStateLimitMax           = 10
+)
+
+// OAuth Purpose Constants
+const (
+	OAuthPurposeLogin = "login"
+	OAuthPurposeBind  = "bind"
+)
+
+// Auth Source Types
+const (
+	AuthSourceTypeOIDC = "oidc"
+)

backend/plugins/domain/auth/errs.go

@@ -0,0 +1,39 @@
+// Copyright 2025 linux.do
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package auth
+
+// OAuth and Auth error messages
+const (
+	errInvalidState                    = "非法登录请求"
+	errIDTokenVerifyFailed             = "ID Token 验证失败" //nolint:gosec // false positive: this is an error message, not hardcoded credentials
+	errIDTokenVerifyFailedFormat       = "%s: %w"
+	errNonceMismatch                   = "nonce 不匹配，可能存在重放攻击"
+	errNoActiveAuthSource              = "未配置可用认证源"
+	errServerAddressMissing            = "服务器地址 (server_address) 未配置或配置为空，请在后台系统设置中配置后再试"
+	errAuthSourceRequired              = "认证源不能为空"
+	errDiscoveryURLRequired            = "OIDC 认证源必须配置 Discovery URL"
+	errUsernameGenerateFailed          = "无法生成可用用户名"
+	errUsernameFromSourceFailed        = "无法从认证源获取用户名"
+	errAuthSourceDisabled              = "认证源未启用"
+	errInvalidExternalAccountBindingID = "绑定记录 ID 无效"
+	ErrTokenAuthNotAllowed             = "该端点不允许使用访问令牌进行身份验证" //nolint:gosec // false positive: this is an error message, not hardcoded credentials
+	errOAuthStateRateLimited           = "请求授权过于频繁，请稍后重试"
+	errAuthSourceNameRequired          = "认证源名称不能为空"
+	errAuthSourceNameInvalid           = "认证源名称格式不正确"
+	errAuthSourceTypeUnsupported       = "不支持的认证源类型"
+	errAuthSourceDiscoveryURLRequired  = "Discovery URL 不能为空"
+	//nolint:gosec // error message, not hardcoded credentials
+	errAuthSourceClientCredentialsRequired  = "启用认证源时必须配置 Client ID 和 Client Secret"
+	errAuthSourceIDRequired                 = "认证源 ID 不能为空"
+	errUserIDRequired                       = "用户 ID 不能为空"
+	errExternalAccountBindingIncomplete     = "外部帐号绑定信息不完整"
+	errExternalAccountAlreadyBoundToAnother = "该外部帐号已被其他用户绑定"
+	errExternalAccountBindingIDRequired     = "外部帐号绑定记录 ID 不能为空"
+	errAdminRequired                        = "无权访问"
+	//nolint:gosec // error message, not hardcoded credentials
+	errTokenAdminRequired = "令牌无管理员权限"
+	errBannedAccount      = "账号已被封禁"
+	errUnAuthorized       = "未登录"
+)

backend/plugins/domain/auth/handlers.go

@@ -0,0 +1,492 @@
+// Copyright 2025 linux.do
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package auth
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"net/http"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/Rain-kl/Wavelet/backend/core/contracts"
+
+	"github.com/Rain-kl/Wavelet/backend/pkg/idgen"
+	"github.com/Rain-kl/Wavelet/backend/pkg/logger"
+	"github.com/Rain-kl/Wavelet/backend/pkg/response"
+	"github.com/Rain-kl/Wavelet/backend/pkg/util"
+	cachepkg "github.com/Rain-kl/Wavelet/backend/plugins/infra/cache"
+	db "github.com/Rain-kl/Wavelet/backend/plugins/infra/database"
+	"github.com/coreos/go-oidc/v3/oidc"
+	"github.com/gin-contrib/sessions"
+	"github.com/gin-gonic/gin"
+	"github.com/google/uuid"
+	"gorm.io/gorm"
+)
+
+// GetLoginSources 获取可用登录源列表
+func GetLoginSources(c *gin.Context) {
+	c.JSON(http.StatusOK, response.OK(activeLoginSources(c.Request.Context())))
+}
+
+// GetLoginURL 获取登录授权地址
+func GetLoginURL(c *gin.Context) {
+	ctx := c.Request.Context()
+	if !isOIDCLoginEnabled(ctx) {
+		response.AbortBadRequest(c, errAuthSourceDisabled)
+		return
+	}
+
+	source, err := resolveAuthSource(ctx, c.Query("source"))
+	if err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+
+	if !source.IsActive {
+		response.AbortBadRequest(c, errAuthSourceDisabled)
+		return
+	}
+
+	session := sessions.Default(c)
+	token, isNew := ensureSessionToken(session)
+	if isNew {
+		if err := session.Save(); err != nil {
+			response.AbortInternal(c, err.Error())
+			return
+		}
+	}
+
+	userID := GetUserIDFromSession(session)
+	sessionHash := hashSessionToken(token)
+	if err := reserveOAuthStateSlot(ctx, sessionHash); err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+
+	state := uuid.NewString()
+	payloadValue, err := encodeOAuthStatePayload(oauthStatePayload{
+		SourceName:  source.Name,
+		Purpose:     OAuthPurposeLogin,
+		UserID:      userID,
+		SessionHash: sessionHash,
+	})
+	if err != nil {
+		response.AbortInternal(c, err.Error())
+		return
+	}
+	if err := cachepkg.Redis.Set(ctx, cachepkg.PrefixedKey(fmt.Sprintf(OAuthStateCacheKeyFormat, state)), payloadValue, OAuthStateCacheKeyExpiration).Err(); err != nil {
+		response.AbortInternal(c, err.Error())
+		return
+	}
+
+	authorizeURL, err := buildAuthorizeURL(c.Request.Context(), source, state)
+	if err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+	c.JSON(http.StatusOK, response.OK(OAuthAuthorizeResponse{AuthorizeURL: authorizeURL}))
+}
+
+func buildAuthorizeURL(ctx context.Context, source *AuthSource, state string) (string, error) {
+	redirectURL, err := getFrontendLoginRedirectURL(ctx)
+	if err != nil {
+		return "", err
+	}
+	authConfig, verifier, err := buildOAuthConfig(ctx, source, redirectURL)
+	if err != nil {
+		return "", err
+	}
+	if verifier != nil {
+		return authConfig.AuthCodeURL(state, oidc.Nonce(state)), nil
+	}
+	return authConfig.AuthCodeURL(state), nil
+}
+
+func reserveOAuthStateSlot(ctx context.Context, sessionHash string) error {
+	if cachepkg.Redis == nil || sessionHash == "" {
+		return nil
+	}
+	key := cachepkg.PrefixedKey(fmt.Sprintf(oauthStateLimitKeyFormat, sessionHash))
+	n, err := cachepkg.Redis.Incr(ctx, key).Result()
+	if err != nil {
+		return err
+	}
+	if n == 1 {
+		_ = cachepkg.Redis.Expire(ctx, key, OAuthStateCacheKeyExpiration).Err()
+	}
+	if n > oauthStateLimitMax {
+		return errors.New(errOAuthStateRateLimited)
+	}
+	return nil
+}
+
+// Authorize 发起指定认证源授权
+func Authorize(c *gin.Context) {
+	ctx := c.Request.Context()
+	if !isOIDCLoginEnabled(ctx) {
+		response.AbortBadRequest(c, errAuthSourceDisabled)
+		return
+	}
+
+	source, err := resolveAuthSource(ctx, c.Param("source"))
+	if err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+
+	if !source.IsActive {
+		response.AbortBadRequest(c, errAuthSourceDisabled)
+		return
+	}
+	purpose := strings.ToLower(strings.TrimSpace(c.Query("purpose")))
+	if purpose != OAuthPurposeBind {
+		purpose = OAuthPurposeLogin
+	}
+
+	session := sessions.Default(c)
+	userID := GetUserIDFromSession(session)
+	if purpose == OAuthPurposeBind && userID == 0 {
+		response.AbortUnauthorized(c, errUnAuthorized)
+		return
+	}
+
+	token, isNew := ensureSessionToken(session)
+	if isNew {
+		if err := session.Save(); err != nil {
+			response.AbortInternal(c, err.Error())
+			return
+		}
+	}
+
+	sessionHash := hashSessionToken(token)
+	if err := reserveOAuthStateSlot(ctx, sessionHash); err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+
+	state := uuid.NewString()
+	payloadValue, err := encodeOAuthStatePayload(oauthStatePayload{
+		SourceName:  source.Name,
+		Purpose:     purpose,
+		UserID:      userID,
+		SessionHash: sessionHash,
+	})
+	if err != nil {
+		response.AbortInternal(c, err.Error())
+		return
+	}
+	if err := cachepkg.Redis.Set(ctx, cachepkg.PrefixedKey(fmt.Sprintf(OAuthStateCacheKeyFormat, state)), payloadValue, OAuthStateCacheKeyExpiration).Err(); err != nil {
+		response.AbortInternal(c, err.Error())
+		return
+	}
+
+	authorizeURL, err := buildAuthorizeURL(c.Request.Context(), source, state)
+	if err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+	c.JSON(http.StatusOK, response.OK(OAuthAuthorizeResponse{AuthorizeURL: authorizeURL}))
+}
+
+// Callback OAuth 回调处理
+func Callback(c *gin.Context) {
+	var req CallbackRequest
+	if err := c.ShouldBindJSON(&req); err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+
+	ctx := c.Request.Context()
+	stateKey := cachepkg.PrefixedKey(fmt.Sprintf(OAuthStateCacheKeyFormat, req.State))
+	payloadRaw, err := cachepkg.Redis.Get(ctx, stateKey).Result()
+	if err != nil {
+		response.AbortBadRequest(c, errInvalidState)
+		return
+	}
+	_ = cachepkg.Redis.Del(ctx, stateKey)
+
+	payload, err := decodeOAuthStatePayload(payloadRaw)
+	if err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+
+	session := sessions.Default(c)
+	currentUserID := GetUserIDFromSession(session)
+
+	if payload.Purpose == OAuthPurposeBind && currentUserID == 0 {
+		response.AbortUnauthorized(c, errUnAuthorized)
+		return
+	}
+
+	token, ok := session.Get(SessionTokenKey).(string)
+	if !ok || token == "" {
+		response.AbortBadRequest(c, "invalid session context")
+		return
+	}
+
+	if hashSessionToken(token) != payload.SessionHash {
+		response.AbortBadRequest(c, "session mismatch for oauth state")
+		return
+	}
+
+	if payload.Purpose == OAuthPurposeBind && currentUserID != payload.UserID {
+		response.AbortBadRequest(c, "user context mismatch for oauth binding")
+		return
+	}
+
+	if !isOIDCLoginEnabled(ctx) {
+		response.AbortBadRequest(c, errAuthSourceDisabled)
+		return
+	}
+
+	source, err := resolveAuthSource(ctx, payload.SourceName)
+	if err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+
+	if !source.IsActive {
+		response.AbortBadRequest(c, errAuthSourceDisabled)
+		return
+	}
+
+	redirectURL, err := getFrontendLoginRedirectURL(ctx)
+	if err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+
+	userInfo, err := buildOAuthUserInfo(ctx, source, req.Code, req.State, redirectURL)
+	if err != nil {
+		response.AbortInternal(c, err.Error())
+		return
+	}
+	if err := normalizeOAuthUserInfo(userInfo); err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+	if userInfo.Sub == "" {
+		userInfo.Sub = userInfo.Username
+	}
+
+	if payload.Purpose == OAuthPurposeBind {
+		handleCallbackBind(ctx, c, source, userInfo)
+		return
+	}
+
+	handleCallbackLogin(ctx, c, source, userInfo)
+}
+
+func handleCallbackBind(ctx context.Context, c *gin.Context, source *AuthSource, userInfo *contracts.OAuthUserInfoDTO) {
+	userID := GetUserIDFromContext(c)
+	if userID == 0 {
+		response.AbortUnauthorized(c, errUnAuthorized)
+		return
+	}
+	var user contracts.UserDTO
+	if err := db.DB(ctx).Table("w_users").Where("id = ?", userID).First(&user).Error; err != nil {
+		response.AbortInternal(c, err.Error())
+		return
+	}
+	if err := BindExternalAccount(ctx, &ExternalAccount{
+		AuthSourceID:     source.ID,
+		UserID:           user.ID,
+		ExternalID:       userInfo.Sub,
+		ExternalUsername: userInfo.Username,
+		Email:            userInfo.Email,
+	}); err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+	user.LastLoginAt = time.Now()
+	_ = db.DB(ctx).Table("w_users").Where("id = ?", user.ID).Update("last_login_at", user.LastLoginAt).Error
+	c.JSON(http.StatusOK, response.OK(buildCallbackResult(&user, "bound")))
+}
+
+func handleCallbackLogin(ctx context.Context, c *gin.Context, source *AuthSource, userInfo *contracts.OAuthUserInfoDTO) {
+	var user contracts.UserDTO
+
+	account, err := FindExternalAccount(ctx, source.ID, userInfo.Sub)
+	switch {
+	case err == nil:
+		if loadErr := db.DB(ctx).Table("w_users").Where("id = ?", account.UserID).First(&user).Error; loadErr != nil {
+			response.AbortInternal(c, loadErr.Error())
+			return
+		}
+	case errors.Is(err, gorm.ErrRecordNotFound):
+		newUser, ok := handleCallbackRegister(ctx, c, source, userInfo)
+		if !ok {
+			return
+		}
+		user = newUser
+	default:
+		response.AbortInternal(c, err.Error())
+		return
+	}
+
+	user.LastLoginAt = time.Now()
+	_ = db.DB(ctx).Table("w_users").Where("id = ?", user.ID).Update("last_login_at", user.LastLoginAt).Error
+	if err := SetLoginSession(ctx, c, &user); err != nil {
+		response.AbortInternal(c, err.Error())
+		return
+	}
+
+	SetCachedUser(ctx, user.ID, &user)
+
+	c.JSON(http.StatusOK, response.OK(buildCallbackResult(&user, "logged_in")))
+}
+
+func uniqueUsername(ctx context.Context, base string) (string, error) {
+	base = strings.TrimSpace(base)
+	if base == "" {
+		base = "user"
+	}
+
+	var existingUsernames []string
+	if err := db.DB(ctx).Table("w_users").
+		Where("username = ? OR username LIKE ? ESCAPE '\\'", base, util.EscapeLike(base)+"-%").
+		Pluck("username", &existingUsernames).Error; err != nil {
+		return "", err
+	}
+
+	exists := make(map[string]bool, len(existingUsernames))
+	for _, u := range existingUsernames {
+		exists[strings.ToLower(u)] = true
+	}
+
+	if !exists[strings.ToLower(base)] {
+		return base, nil
+	}
+
+	for i := 1; i <= 1000; i++ {
+		candidate := fmt.Sprintf("%s-%d", base, i)
+		if !exists[strings.ToLower(candidate)] {
+			return candidate, nil
+		}
+	}
+
+	return "", errors.New(errUsernameGenerateFailed)
+}
+
+func handleCallbackRegister(ctx context.Context, c *gin.Context, source *AuthSource, userInfo *contracts.OAuthUserInfoDTO) (contracts.UserDTO, bool) {
+	registrationEnabled := true
+	var val string
+	if err := db.DB(ctx).Table("w_system_configs").Where("key = ?", "registration_enabled").Pluck("value", &val).Error; err == nil && val != "" {
+		if b, err := strconv.ParseBool(val); err == nil {
+			registrationEnabled = b
+		}
+	}
+
+	if !registrationEnabled {
+		c.JSON(http.StatusOK, response.OK(buildCallbackResult(nil, "need_bind")))
+		return contracts.UserDTO{}, false
+	}
+
+	username, uniqueErr := uniqueUsername(ctx, userInfo.Username)
+	if uniqueErr != nil {
+		response.AbortInternal(c, uniqueErr.Error())
+		return contracts.UserDTO{}, false
+	}
+	userInfo.Username = username
+
+	now := time.Now()
+	user := contracts.UserDTO{
+		ID:          idgen.NextUint64ID(),
+		Username:    userInfo.Username,
+		Nickname:    userInfo.Name,
+		Email:       userInfo.Email,
+		AvatarURL:   userInfo.AvatarURL,
+		IsActive:    userInfo.Active,
+		LastLoginAt: now,
+		CreatedAt:   now,
+		UpdatedAt:   now,
+	}
+
+	if err := db.DB(ctx).Table("w_users").Create(&user).Error; err != nil {
+		response.AbortInternal(c, err.Error())
+		return contracts.UserDTO{}, false
+	}
+
+	if err := BindExternalAccount(ctx, &ExternalAccount{
+		AuthSourceID:     source.ID,
+		UserID:           user.ID,
+		ExternalID:       userInfo.Sub,
+		ExternalUsername: userInfo.Username,
+		Email:            userInfo.Email,
+	}); err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return contracts.UserDTO{}, false
+	}
+	logger.InfoF(ctx, "[LoginAudit] successful OAuth registration via source: %s, external ID: %s, user: %s, ID: %d, IP: %s", source.Name, userInfo.Sub, user.Username, user.ID, c.ClientIP())
+
+	return user, true
+}
+
+// UserInfo 获取当前登录用户信息
+func UserInfo(c *gin.Context) {
+	user, _ := util.GetFromContext[*contracts.UserDTO](c, contracts.AuthUserObjKey)
+	session := sessions.Default(c)
+	needChange := session.Get("need_change_password") == true
+
+	c.JSON(
+		http.StatusOK,
+		response.OK(BuildBasicUserInfo(user, needChange)),
+	)
+}
+
+// Logout 退出登录
+func Logout(c *gin.Context) {
+	session := sessions.Default(c)
+	userID := session.Get(UserIDKey)
+	username := session.Get(UserNameKey)
+	if userID != nil {
+		logger.InfoF(c.Request.Context(), "[LoginAudit] user logged out: %v, ID: %v, IP: %s", username, userID, c.ClientIP())
+		if id := ParseUserID(userID); id > 0 {
+			InvalidateCachedUser(c.Request.Context(), id)
+		}
+	}
+	session.Options(GetSessionOptions(-1))
+	session.Clear()
+	if err := session.Save(); err != nil {
+		response.AbortInternal(c, err.Error())
+		return
+	}
+	c.JSON(http.StatusOK, response.OKNil())
+}
+
+// ListExternalAccounts 获取当前用户的外部帐号绑定列表
+func ListExternalAccounts(c *gin.Context) {
+	userID := GetUserIDFromContext(c)
+	accounts, err := ListExternalAccountsByUserID(c.Request.Context(), userID)
+	if err != nil {
+		response.AbortInternal(c, err.Error())
+		return
+	}
+	c.JSON(http.StatusOK, response.OK(accounts))
+}
+
+// DeleteExternalAccount 解除外部帐号绑定
+func DeleteExternalAccount(c *gin.Context) {
+	userID := GetUserIDFromContext(c)
+	if userID == 0 {
+		response.AbortUnauthorized(c, errUnAuthorized)
+		return
+	}
+	rawID := strings.TrimSpace(c.Param("id"))
+	id, err := strconv.ParseUint(rawID, 10, 64)
+	if err != nil || id == 0 {
+		response.AbortBadRequest(c, errInvalidExternalAccountBindingID)
+		return
+	}
+	if err := UnbindExternalAccount(c.Request.Context(), id, userID); err != nil {
+		response.AbortBadRequest(c, err.Error())
+		return
+	}
+	c.JSON(http.StatusOK, response.OKNil())
+}

backend/plugins/domain/auth/middleware.go

@@ -0,0 +1,176 @@
+// Copyright 2025 linux.do
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package auth
+
+import (
+	"context"
+	"crypto/sha256"
+	"encoding/hex"
+	"errors"
+
+	"github.com/Rain-kl/Wavelet/backend/core/contracts"
+	"github.com/Rain-kl/Wavelet/backend/pkg/response"
+	"github.com/Rain-kl/Wavelet/backend/pkg/trace"
+	"github.com/Rain-kl/Wavelet/backend/pkg/util"
+	db "github.com/Rain-kl/Wavelet/backend/plugins/infra/database"
+	"github.com/gin-gonic/gin"
+)
+
+func hashToken(token string) string {
+	h := sha256.New()
+	h.Write([]byte(token))
+	return hex.EncodeToString(h.Sum(nil))
+}
+
+func getUserByToken(ctx context.Context, tokenStr string) (*contracts.UserDTO, *CachedToken, error) {
+	tokenHash := hashToken(tokenStr)
+	tokenRecord, err := GetCachedToken(ctx, tokenHash)
+	if err == nil {
+		user, err := GetCachedUser(ctx, tokenRecord.UserID)
+		if err == nil && user != nil && user.IsActive {
+			return user, tokenRecord, nil
+		}
+	}
+
+	var tokenRow struct {
+		ID      uint64
+		UserID  uint64
+		IsAdmin bool
+	}
+	if err := db.DB(ctx).Table("w_access_tokens").Where("token_hash = ?", tokenHash).First(&tokenRow).Error; err != nil {
+		return nil, nil, err
+	}
+	tokenRecord = &CachedToken{
+		ID:      tokenRow.ID,
+		UserID:  tokenRow.UserID,
+		IsAdmin: tokenRow.IsAdmin,
+	}
+	SetCachedToken(ctx, tokenHash, tokenRecord)
+
+	var userRow contracts.UserDTO
+	if err := db.DB(ctx).Table("w_users").Where("id = ? AND is_active = ?", tokenRow.UserID, true).First(&userRow).Error; err != nil {
+		return nil, nil, err
+	}
+	SetCachedUser(ctx, userRow.ID, &userRow)
+	return &userRow, tokenRecord, nil
+}
+
+// GetUserFromRequest 校验 Access Token 或 Session 并返回用户对象，如果未登录或用户失效则返回 error
+func GetUserFromRequest(c *gin.Context) (*contracts.UserDTO, error) {
+	ctx := c.Request.Context()
+
+	// Check token in headers
+	tokenStr := c.GetHeader("X-Access-Token")
+	if tokenStr == "" {
+		authHeader := c.GetHeader("Authorization")
+		if len(authHeader) > 7 && authHeader[:7] == "Bearer " {
+			tokenStr = authHeader[7:]
+		}
+	}
+
+	// 优先使用 Access Token 鉴权
+	if tokenStr != "" {
+		if user, tokenRecord, err := getUserByToken(ctx, tokenStr); err == nil {
+			if user.Username == SystemUsername {
+				return nil, errors.New("system user is not allowed to login")
+			}
+			util.SetToContext(c, contracts.AuthTokenAuthKey, true)
+			util.SetToContext(c, contracts.AuthTokenAdminKey, tokenRecord.IsAdmin)
+			return user, nil
+		}
+	}
+
+	// 降级使用 Session 鉴权
+	userID := GetUserIDFromContext(c)
+	if userID <= 0 {
+		return nil, errors.New("unauthorized")
+	}
+
+	user, err := GetCachedUser(ctx, userID)
+	if err != nil || user == nil || !user.IsActive {
+		var dbUser contracts.UserDTO
+		if err := db.DB(ctx).Table("w_users").Where("id = ? AND is_active = ?", userID, true).First(&dbUser).Error; err != nil {
+			return nil, err
+		}
+		user = &dbUser
+		SetCachedUser(ctx, userID, user)
+	}
+
+	util.SetToContext(c, contracts.AuthTokenAuthKey, false)
+	util.SetToContext(c, contracts.AuthTokenAdminKey, false)
+
+	if user.Username == "system" {
+		return nil, errors.New("system user is not allowed to login")
+	}
+
+	return user, nil
+}
+
+// LoginRequired 返回登录鉴权中间件，校验 Access Token 或 Session
+func LoginRequired() gin.HandlerFunc {
+	return func(c *gin.Context) {
+		_, span := trace.Start(c.Request.Context(), "LoginRequired")
+		defer span.End()
+
+		user, err := GetUserFromRequest(c)
+		if err != nil {
+			response.AbortUnauthorized(c, errUnAuthorized)
+			return
+		}
+
+		LogForAudit(c.Request.Context(), user, c)
+		util.SetToContext(c, contracts.AuthUserObjKey, user)
+		c.Next()
+	}
+}
+
+// AdminRequired 校验管理员权限（支持 Session 和 Token 鉴权）
+func AdminRequired() gin.HandlerFunc {
+	return func(c *gin.Context) {
+		_, span := trace.Start(c.Request.Context(), "AdminRequired")
+		defer span.End()
+
+		user, err := GetUserFromRequest(c)
+		if err != nil {
+			response.AbortUnauthorized(c, errUnAuthorized)
+			return
+		}
+
+		isTokenAuth, _ := util.GetFromContext[bool](c, contracts.AuthTokenAuthKey)
+		isTokenAdmin, _ := util.GetFromContext[bool](c, contracts.AuthTokenAdminKey)
+
+		// 如果是通过 Token 鉴权，要求该 Token 具备管理员权限或者用户本身为管理员
+		if isTokenAuth && !isTokenAdmin && !user.IsAdmin {
+			response.AbortNotFound(c, errTokenAdminRequired)
+			return
+		}
+
+		// 如果是通过 Session 鉴权，直接检查用户的 is_admin 属性
+		if !isTokenAuth && !user.IsAdmin {
+			response.AbortNotFound(c, errAdminRequired)
+			return
+		}
+
+		LogForAudit(c.Request.Context(), user, c)
+		util.SetToContext(c, contracts.AuthUserObjKey, user)
+		c.Next()
+	}
+}
+
+// LoginAdminRequired is an alias for AdminRequired.
+func LoginAdminRequired() gin.HandlerFunc {
+	return AdminRequired()
+}
+
+// DisallowTokenAuth 拒绝使用 Access Token 进行身份验证的请求访问该端点
+func DisallowTokenAuth() gin.HandlerFunc {
+	return func(c *gin.Context) {
+		if tokenAuth, _ := util.GetFromContext[bool](c, contracts.AuthTokenAuthKey); tokenAuth {
+			response.AbortForbidden(c, ErrTokenAuthNotAllowed)
+			return
+		}
+		c.Next()
+	}
+}

backend/plugins/domain/auth/migrations/00001_initial.sql

@@ -0,0 +1,58 @@
+-- +goose Up
+-- +goose StatementBegin
+CREATE TABLE IF NOT EXISTS w_auth_sources (
+    id BIGINT PRIMARY KEY,
+    name VARCHAR(80) NOT NULL UNIQUE,
+    type VARCHAR(20) NOT NULL,
+    display_name VARCHAR(100),
+    is_active BOOLEAN NOT NULL DEFAULT FALSE,
+    client_id VARCHAR(255),
+    client_secret VARCHAR(1024),
+    openid_discovery_url VARCHAR(1024),
+    scopes VARCHAR(255),
+    icon_url VARCHAR(1024),
+    created_at TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP,
+    updated_at TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP
+);
+CREATE INDEX IF NOT EXISTS idx_w_auth_sources_is_active ON w_auth_sources (is_active);
+
+CREATE TABLE IF NOT EXISTS w_external_accounts (
+    id BIGINT PRIMARY KEY,
+    auth_source_id BIGINT,
+    user_id BIGINT NOT NULL,
+    external_id VARCHAR(255) NOT NULL,
+    external_username VARCHAR(255),
+    email VARCHAR(255),
+    created_at TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP,
+    updated_at TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP
+);
+CREATE INDEX IF NOT EXISTS idx_w_external_accounts_auth_source_id ON w_external_accounts (auth_source_id);
+CREATE INDEX IF NOT EXISTS idx_w_external_accounts_user_id ON w_external_accounts (user_id);
+CREATE UNIQUE INDEX IF NOT EXISTS idx_w_external_accounts_source_external ON w_external_accounts (auth_source_id, external_id);
+
+CREATE TABLE IF NOT EXISTS w_access_tokens (
+    id BIGINT PRIMARY KEY,
+    user_id BIGINT NOT NULL,
+    token_hash VARCHAR(64) NOT NULL UNIQUE,
+    name VARCHAR(128) NOT NULL,
+    description VARCHAR(255),
+    is_admin BOOLEAN DEFAULT FALSE,
+    expires_at TIMESTAMPTZ,
+    created_at TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP,
+    updated_at TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP
+);
+CREATE INDEX IF NOT EXISTS idx_w_access_tokens_user_id ON w_access_tokens (user_id);
+
+-- Seed: login session TTL
+INSERT INTO w_system_configs (key, value, type, visibility, description, created_at, updated_at)
+VALUES ('login_session_ttl_hours', '0', 'system', 0, '登录会话过期时间 (小时，0表示浏览器关闭后自动退出，-1表示永不过期)', CURRENT_TIMESTAMP, CURRENT_TIMESTAMP)
+ON CONFLICT (key) DO NOTHING;
+-- +goose StatementEnd
+
+-- +goose Down
+-- +goose StatementBegin
+DELETE FROM w_system_configs WHERE key = 'login_session_ttl_hours';
+DROP TABLE IF EXISTS w_access_tokens;
+DROP TABLE IF EXISTS w_external_accounts;
+DROP TABLE IF EXISTS w_auth_sources;
+-- +goose StatementEnd

backend/plugins/domain/auth/models.go

@@ -0,0 +1,243 @@
+// Copyright 2025 linux.do
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package auth
+
+import (
+	"encoding/json"
+	"errors"
+	"regexp"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/Rain-kl/Wavelet/backend/core/contracts"
+)
+
+var authSourceNamePattern = regexp.MustCompile(`^[A-Za-z0-9][A-Za-z0-9_-]{0,79}$`)
+
+// AuthSource 认证源实体
+//
+//nolint:revive // auth.AuthSource is standard domain entity name
+type AuthSource struct {
+	ID                     uint64    `json:"id" gorm:"primaryKey"`
+	Name                   string    `json:"name" gorm:"uniqueIndex;size:80;not null"`
+	Type                   string    `json:"type" gorm:"size:20;not null"`
+	DisplayName            string    `json:"display_name" gorm:"size:100"`
+	IsActive               bool      `json:"is_active" gorm:"index;not null;default:false"`
+	ClientID               string    `json:"client_id" gorm:"size:255"`
+	ClientSecret           string    `json:"-" gorm:"size:1024"`
+	OpenIDDiscoveryURL     string    `json:"openid_discovery_url" gorm:"column:openid_discovery_url;size:1024"`
+	Scopes                 string    `json:"scopes" gorm:"size:255"`
+	IconURL                string    `json:"icon_url" gorm:"size:1024"`
+	CreatedAt              time.Time `json:"created_at"`
+	UpdatedAt              time.Time `json:"updated_at"`
+	ClientSecretConfigured bool      `json:"client_secret_configured" gorm:"-"`
+}
+
+// TableName 表名
+func (AuthSource) TableName() string {
+	return "w_auth_sources"
+}
+
+// Normalize 对认证源字段进行标准化处理
+func (source *AuthSource) Normalize() {
+	source.Type = strings.ToLower(strings.TrimSpace(source.Type))
+	source.Name = strings.TrimSpace(source.Name)
+	source.DisplayName = strings.TrimSpace(source.DisplayName)
+	source.ClientID = strings.TrimSpace(source.ClientID)
+	source.ClientSecret = strings.TrimSpace(source.ClientSecret)
+	source.OpenIDDiscoveryURL = strings.TrimSpace(source.OpenIDDiscoveryURL)
+	source.Scopes = strings.TrimSpace(source.Scopes)
+	source.IconURL = strings.TrimSpace(source.IconURL)
+	if source.DisplayName == "" {
+		source.DisplayName = source.Name
+	}
+	if source.Type == AuthSourceTypeOIDC && source.Scopes == "" {
+		source.Scopes = "openid profile email"
+	}
+}
+
+// Validate 校验认证源字段合法性
+func (source *AuthSource) Validate() error {
+	source.Normalize()
+	if source.Name == "" {
+		return errors.New(errAuthSourceNameRequired)
+	}
+	if !authSourceNamePattern.MatchString(source.Name) {
+		return errors.New(errAuthSourceNameInvalid)
+	}
+	if source.Type != AuthSourceTypeOIDC {
+		return errors.New(errAuthSourceTypeUnsupported)
+	}
+	if source.OpenIDDiscoveryURL == "" {
+		//nolint:staticcheck // descriptive error constant
+		return errors.New(errAuthSourceDiscoveryURLRequired)
+	}
+	if source.IsActive && (source.ClientID == "" || source.ClientSecret == "") {
+		return errors.New(errAuthSourceClientCredentialsRequired)
+	}
+	return nil
+}
+
+// Sanitize 脱敏处理，将 ClientSecret 清空并设置 ClientSecretConfigured 标志
+func (source *AuthSource) Sanitize() {
+	source.ClientSecretConfigured = source.ClientSecret != ""
+	source.ClientSecret = ""
+}
+
+// ExternalAccount 外部账号绑定实体
+type ExternalAccount struct {
+	ID               uint64    `json:"id" gorm:"primaryKey"`
+	AuthSourceID     uint64    `json:"auth_source_id" gorm:"uniqueIndex:idx_external_accounts_source_external,priority:1;index"`
+	UserID           uint64    `json:"user_id" gorm:"index;not null"`
+	ExternalID       string    `json:"external_id" gorm:"uniqueIndex:idx_external_accounts_source_external,priority:2;size:255;not null"`
+	ExternalUsername string    `json:"external_username" gorm:"size:255"`
+	Email            string    `json:"email" gorm:"size:255"`
+	CreatedAt        time.Time `json:"created_at"`
+	UpdatedAt        time.Time `json:"updated_at"`
+}
+
+// TableName 表名
+func (ExternalAccount) TableName() string {
+	return "w_external_accounts"
+}
+
+// ExternalAccountView 外部帐号绑定视图（脱敏展示用）
+type ExternalAccountView struct {
+	ID               uint64    `json:"id"`
+	AuthSourceID     uint64    `json:"auth_source_id"`
+	AuthSourceName   string    `json:"auth_source_name"`
+	AuthSourceType   string    `json:"auth_source_type"`
+	AuthSourceLabel  string    `json:"auth_source_label"`
+	ExternalUsername string    `json:"external_username"`
+	Email            string    `json:"email"`
+	CreatedAt        time.Time `json:"created_at"`
+}
+
+// AuthSourceView 登录源展示信息
+//
+//nolint:revive // auth.AuthSourceView is standard domain presentation struct
+type AuthSourceView struct {
+	ID                     uint64 `json:"id"`
+	Name                   string `json:"name"`
+	Type                   string `json:"type"`
+	DisplayName            string `json:"display_name"`
+	IsActive               bool   `json:"is_active"`
+	IconURL                string `json:"icon_url"`
+	ClientSecretConfigured bool   `json:"client_secret_configured"`
+}
+
+// OAuthAuthorizeResponse 授权 URL 响应
+type OAuthAuthorizeResponse struct {
+	AuthorizeURL string `json:"authorize_url"`
+}
+
+// OAuthCallbackResult 回调处理结果
+type OAuthCallbackResult struct {
+	Status string         `json:"status"`
+	User   *BasicUserInfo `json:"user,omitempty"`
+}
+
+// CallbackRequest OAuth 回调请求参数
+type CallbackRequest struct {
+	State string `json:"state" binding:"required"`
+	Code  string `json:"code" binding:"required"`
+}
+
+// BasicUserInfo 用户基本信息结构体
+type BasicUserInfo struct {
+	ID                 uint64 `json:"id"`
+	Username           string `json:"username"`
+	Nickname           string `json:"nickname"`
+	Email              string `json:"email"`
+	AvatarURL          string `json:"avatar_url"`
+	IsAdmin            bool   `json:"is_admin"`
+	NeedChangePassword bool   `json:"need_change_password"`
+	Bio                string `json:"bio"`
+	Phone              string `json:"phone"`
+	Gender             string `json:"gender"`
+	Website            string `json:"website"`
+	Location           string `json:"location"`
+}
+
+// BuildBasicUserInfo 将 UserDTO 转换为 BasicUserInfo
+func BuildBasicUserInfo(user *contracts.UserDTO, needChange bool) BasicUserInfo {
+	if user == nil {
+		return BasicUserInfo{}
+	}
+	return BasicUserInfo{
+		ID:                 user.ID,
+		Username:           user.Username,
+		Nickname:           user.Nickname,
+		Email:              user.Email,
+		AvatarURL:          user.AvatarURL,
+		IsAdmin:            user.IsAdmin,
+		NeedChangePassword: needChange,
+		Bio:                user.Bio,
+		Phone:              user.Phone,
+		Gender:             user.Gender,
+		Website:            user.Website,
+		Location:           user.Location,
+	}
+}
+
+type oauthStatePayload struct {
+	SourceName  string `json:"source_name"`
+	Purpose     string `json:"purpose"`
+	UserID      uint64 `json:"user_id,omitempty"`
+	SessionHash string `json:"session_hash"`
+}
+
+func encodeOAuthStatePayload(payload oauthStatePayload) (string, error) {
+	data, err := json.Marshal(payload)
+	if err != nil {
+		return "", err
+	}
+	return string(data), nil
+}
+
+func decodeOAuthStatePayload(value string) (oauthStatePayload, error) {
+	var payload oauthStatePayload
+	if err := json.Unmarshal([]byte(value), &payload); err != nil {
+		return oauthStatePayload{}, err
+	}
+	return payload, nil
+}
+
+type loginRequiredAuditLog struct {
+	UserID     uint64 `json:"user_id"`
+	Username   string `json:"username"`
+	ClientIP   string `json:"client_ip"`
+	Method     string `json:"method"`
+	Path       string `json:"path"`
+	RequestURI string `json:"request_uri"`
+	UserAgent  string `json:"user_agent"`
+	Referer    string `json:"referer"`
+}
+
+// ParseUserID parses a string or float64 user ID representation.
+func ParseUserID(v any) uint64 {
+	switch val := v.(type) {
+	case uint64:
+		return val
+	case int64:
+		if val > 0 {
+			return uint64(val)
+		}
+	case int:
+		if val > 0 {
+			return uint64(val)
+		}
+	case float64:
+		if val > 0 {
+			return uint64(val)
+		}
+	case string:
+		if id, err := strconv.ParseUint(val, 10, 64); err == nil {
+			return id
+		}
+	}
+	return 0
+}

backend/plugins/domain/auth/plugin.go

@@ -0,0 +1,114 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+// Package auth provides the authentication, OAuth, session management, and access token domain plugin for Cordis.
+package auth
+
+import (
+	"embed"
+
+	"github.com/Rain-kl/Wavelet/backend/core"
+	"github.com/Rain-kl/Wavelet/backend/core/contracts"
+	"github.com/Rain-kl/Wavelet/backend/core/extpoints"
+)
+
+//go:embed migrations/*.sql
+var authMigrations embed.FS
+
+// Option configures the auth plugin.
+type Option func(*Plugin)
+
+// WithAuthService sets a custom AuthService implementation.
+func WithAuthService(svc contracts.AuthService) Option {
+	return func(p *Plugin) {
+		p.authSvc = svc
+	}
+}
+
+// WithAuthRegistry sets a custom AuthRegistry implementation.
+func WithAuthRegistry(reg contracts.AuthRegistry) Option {
+	return func(p *Plugin) {
+		p.authRegistry = reg
+	}
+}
+
+// Plugin implements core.Plugin to provide authentication and OAuth domain services.
+type Plugin struct {
+	authSvc      contracts.AuthService
+	authRegistry contracts.AuthRegistry
+}
+
+// New creates a new auth domain plugin.
+func New(opts ...Option) *Plugin {
+	p := &Plugin{}
+	for _, opt := range opts {
+		if opt != nil {
+			opt(p)
+		}
+	}
+	return p
+}
+
+// Name returns the unique identifier for the auth domain plugin.
+func (p *Plugin) Name() string {
+	return "auth"
+}
+
+// Manifest returns the plugin metadata.
+func (p *Plugin) Manifest() core.Manifest {
+	return core.Manifest{
+		Name:        "auth",
+		Version:     "1.0.0",
+		Description: "Authentication, OAuth, Session and Passkey domain plugin",
+		Author:      "Wavelet Team",
+	}
+}
+
+// Apply registers the auth migrations, services, routes, and settings into the Context.
+func (p *Plugin) Apply(ctx *core.Context) error {
+	// 1. Register migrations
+	ctx.Migrations().Register("auth", authMigrations)
+
+	// 2. Initialize and provide AuthService & AuthRegistry
+	if p.authSvc == nil {
+		p.authSvc = newAuthService()
+	}
+	if p.authRegistry == nil {
+		p.authRegistry = newAuthRegistry()
+	}
+
+	core.Provide[contracts.AuthService](ctx, p.authSvc)
+	core.Provide[contracts.AuthRegistry](ctx, p.authRegistry)
+
+	// 3. Register HTTP Routes
+	oauthGroup := ctx.Router().Group("/api/v1/oauth")
+	{
+		oauthGroup.GET("/sources", GetLoginSources)
+		oauthGroup.GET("/login", GetLoginURL)
+		oauthGroup.GET("/:source/authorize", Authorize)
+		oauthGroup.GET("/logout", Logout)
+		oauthGroup.POST("/callback", Callback)
+		oauthGroup.GET("/user-info", LoginRequired(), UserInfo)
+		oauthGroup.GET("/external-accounts", LoginRequired(), ListExternalAccounts)
+		oauthGroup.POST("/external-accounts/:id/delete", LoginRequired(), DeleteExternalAccount)
+	}
+	ctx.Router().GET("/api/v1/user-info", LoginRequired(), UserInfo)
+
+	// 4. Register Settings Schemas
+	ctx.Settings().Register(extpoints.SettingSchema{
+		Key:         "auth.session_age",
+		Default:     86400 * 7,
+		Description: "Default session lifetime in seconds",
+		Type:        "integer",
+		Category:    "security",
+	})
+	ctx.Settings().Register(extpoints.SettingSchema{
+		Key:         "auth.login_rate_limit_max_attempts",
+		Default:     5,
+		Description: "Max login failure attempts before temporary IP lock",
+		Type:        "integer",
+		Category:    "security",
+	})
+
+	return nil
+}

backend/plugins/domain/auth/plugin_test.go

@@ -0,0 +1,140 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package auth_test
+
+import (
+	"context"
+	"crypto/sha256"
+	"encoding/hex"
+	"path/filepath"
+	"testing"
+	"time"
+
+	"github.com/glebarez/sqlite"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"gorm.io/gorm"
+
+	"github.com/Rain-kl/Wavelet/backend/core"
+	"github.com/Rain-kl/Wavelet/backend/core/contracts"
+	"github.com/Rain-kl/Wavelet/backend/plugins/domain/auth"
+	db "github.com/Rain-kl/Wavelet/backend/plugins/infra/database"
+)
+
+type testUser struct {
+	ID          uint64 `gorm:"primaryKey"`
+	Username    string
+	IsActive    bool
+	LastLoginAt time.Time
+}
+
+func (testUser) TableName() string { return "w_users" }
+
+type testAccessToken struct {
+	ID        uint64 `gorm:"primaryKey"`
+	UserID    uint64
+	TokenHash string
+	Name      string
+	IsAdmin   bool
+}
+
+func (testAccessToken) TableName() string { return "w_access_tokens" }
+
+func hashToken(token string) string {
+	h := sha256.New()
+	h.Write([]byte(token))
+	return hex.EncodeToString(h.Sum(nil))
+}
+
+func setupTestDB(t *testing.T) *gorm.DB {
+	t.Helper()
+	dbPath := filepath.Join(t.TempDir(), "auth_test.db")
+	testDB, err := gorm.Open(sqlite.Open(dbPath), &gorm.Config{})
+	require.NoError(t, err)
+
+	require.NoError(t, testDB.AutoMigrate(
+		&testUser{},
+		&testAccessToken{},
+		&auth.AuthSource{},
+		&auth.ExternalAccount{},
+	))
+
+	db.SetDB(testDB)
+	return testDB
+}
+
+type mockProvider struct{}
+
+func (m *mockProvider) Name() string { return "custom" }
+func (m *mockProvider) GetAuthURL(state string) string {
+	return "https://custom.com/auth?state=" + state
+}
+func (m *mockProvider) ExchangeCode(ctx context.Context, code string) (*contracts.OAuthUserInfoDTO, error) {
+	return &contracts.OAuthUserInfoDTO{
+		ID:       555,
+		Username: "custom_user",
+		Email:    "custom@example.com",
+	}, nil
+}
+
+func TestAuthPluginUnit(t *testing.T) {
+	ctx := core.NewContext(context.Background())
+	testDB := setupTestDB(t)
+
+	p := auth.New()
+	assert.Equal(t, "auth", p.Name())
+	assert.Equal(t, "1.0.0", p.Manifest().Version)
+	require.NoError(t, p.Apply(ctx))
+
+	// Test AuthService injection
+	authSvc, err := core.Inject[contracts.AuthService](ctx)
+	require.NoError(t, err)
+	assert.NotNil(t, authSvc.RequireAuthMiddleware())
+	assert.NotNil(t, authSvc.RequireAdminMiddleware())
+
+	// Test AuthRegistry injection
+	authReg, err := core.Inject[contracts.AuthRegistry](ctx)
+	require.NoError(t, err)
+	authReg.RegisterOAuthProvider("custom", &mockProvider{})
+	prov, ok := authReg.GetOAuthProvider("custom")
+	require.True(t, ok)
+	assert.Equal(t, "custom", prov.Name())
+
+	// Test User Token Verification with dummy token
+	user := testUser{
+		ID:       101,
+		Username: "token_user",
+		IsActive: true,
+	}
+	require.NoError(t, testDB.Create(&user).Error)
+
+	tokenStr := "test-secret-token-123456"
+	tokenHash := hashToken(tokenStr)
+	tokenRecord := testAccessToken{
+		ID:        201,
+		UserID:    user.ID,
+		TokenHash: tokenHash,
+		Name:      "test-token",
+		IsAdmin:   false,
+	}
+	require.NoError(t, testDB.Create(&tokenRecord).Error)
+
+	userDTO, err := authSvc.VerifyToken(context.Background(), tokenStr)
+	require.NoError(t, err)
+	assert.Equal(t, user.ID, userDTO.ID)
+	assert.Equal(t, "token_user", userDTO.Username)
+
+	// Empty token fails
+	_, err = authSvc.VerifyToken(context.Background(), "")
+	assert.Error(t, err)
+
+	// Revoke sessions
+	require.NoError(t, authSvc.RevokeUserSessions(context.Background(), user.ID))
+
+	// GetCurrentUser from context
+	userCtx := context.WithValue(context.Background(), contracts.AuthUserObjKey, userDTO)
+	current, err := authSvc.GetCurrentUser(userCtx)
+	require.NoError(t, err)
+	assert.Equal(t, user.ID, current.ID)
+}

backend/plugins/domain/auth/provider_cache.go

@@ -0,0 +1,81 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package auth
+
+import (
+	"context"
+	"net/http"
+	"sync"
+
+	"github.com/coreos/go-oidc/v3/oidc"
+	"golang.org/x/oauth2"
+	"golang.org/x/sync/singleflight"
+)
+
+// oidcProviderCache 进程级 OIDC provider 缓存。
+type oidcProviderCache struct {
+	mu      sync.RWMutex
+	entries map[string]*oidc.Provider // key: normalized issuer URL
+	sfGroup singleflight.Group
+}
+
+// globalOIDCProviderCache 是包级单例缓存，与进程同生命周期。
+var globalOIDCProviderCache = &oidcProviderCache{
+	entries: make(map[string]*oidc.Provider),
+}
+
+// discoveryContext 从请求 ctx 提取 HTTP 客户端，并绑定到不可取消的 Background ctx。
+func discoveryContext(ctx context.Context) context.Context {
+	bg := context.Background()
+	if client, ok := ctx.Value(oauth2.HTTPClient).(*http.Client); ok && client != nil {
+		bg = oidc.ClientContext(bg, client)
+	}
+	return bg
+}
+
+// get 返回缓存的 provider；若无则通过 oidc.NewProvider 获取并写入缓存。
+func (c *oidcProviderCache) get(ctx context.Context, issuer string) (*oidc.Provider, error) {
+	c.mu.RLock()
+	if p, ok := c.entries[issuer]; ok {
+		c.mu.RUnlock()
+		return p, nil
+	}
+	c.mu.RUnlock()
+
+	discCtx := discoveryContext(ctx)
+	v, err, _ := c.sfGroup.Do(issuer, func() (any, error) {
+		c.mu.RLock()
+		if p, ok := c.entries[issuer]; ok {
+			c.mu.RUnlock()
+			return p, nil
+		}
+		c.mu.RUnlock()
+
+		p, err := oidc.NewProvider(discCtx, issuer)
+		if err != nil {
+			return nil, err
+		}
+
+		c.mu.Lock()
+		c.entries[issuer] = p
+		c.mu.Unlock()
+		return p, nil
+	})
+	if err != nil {
+		return nil, err
+	}
+	return v.(*oidc.Provider), nil //nolint:forcetypeassert
+}
+
+// invalidate 从缓存中移除指定 issuer 对应的 provider。
+func (c *oidcProviderCache) invalidate(issuer string) {
+	c.mu.Lock()
+	delete(c.entries, issuer)
+	c.mu.Unlock()
+}
+
+// InvalidateOIDCProviderCache 从进程级缓存中清除指定 issuer 的 provider 条目。
+func InvalidateOIDCProviderCache(issuer string) {
+	globalOIDCProviderCache.invalidate(issuer)
+}

backend/plugins/domain/auth/repository.go

@@ -0,0 +1,76 @@
+// Copyright 2025 linux.do
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package auth
+
+import (
+	"context"
+
+	db "github.com/Rain-kl/Wavelet/backend/plugins/infra/database"
+)
+
+// GetAuthSourceByID 根据 ID 获取认证源
+func GetAuthSourceByID(ctx context.Context, id uint64) (*AuthSource, error) {
+	var src AuthSource
+	if err := db.DB(ctx).First(&src, id).Error; err != nil {
+		return nil, err
+	}
+	return &src, nil
+}
+
+// GetAuthSourceByName 根据名称获取认证源
+func GetAuthSourceByName(ctx context.Context, name string) (*AuthSource, error) {
+	var src AuthSource
+	if err := db.DB(ctx).Where("name = ?", name).First(&src).Error; err != nil {
+		return nil, err
+	}
+	return &src, nil
+}
+
+// ListActiveAuthSources 获取所有启用的认证源
+func ListActiveAuthSources(ctx context.Context) ([]AuthSource, error) {
+	var sources []AuthSource
+	if err := db.DB(ctx).Where("is_active = ?", true).Order("id ASC").Find(&sources).Error; err != nil {
+		return nil, err
+	}
+	return sources, nil
+}
+
+// GetActiveAuthSourcesCached 获取所有启用的认证源（带缓存或直接查询）
+func GetActiveAuthSourcesCached(ctx context.Context) ([]AuthSource, error) {
+	return ListActiveAuthSources(ctx)
+}
+
+// GetAuthSourceByNameCached 根据名称获取认证源（带缓存或直接查询）
+func GetAuthSourceByNameCached(ctx context.Context, name string) (*AuthSource, error) {
+	return GetAuthSourceByName(ctx, name)
+}
+
+// FindExternalAccount 查询指定认证源的外部账号绑定
+func FindExternalAccount(ctx context.Context, authSourceID uint64, externalID string) (*ExternalAccount, error) {
+	var account ExternalAccount
+	if err := db.DB(ctx).Where("auth_source_id = ? AND external_id = ?", authSourceID, externalID).First(&account).Error; err != nil {
+		return nil, err
+	}
+	return &account, nil
+}
+
+// BindExternalAccount 绑定外部账号
+func BindExternalAccount(ctx context.Context, account *ExternalAccount) error {
+	return db.DB(ctx).Create(account).Error
+}
+
+// ListExternalAccountsByUserID 获取用户绑定的所有外部账号
+func ListExternalAccountsByUserID(ctx context.Context, userID uint64) ([]ExternalAccount, error) {
+	var accounts []ExternalAccount
+	if err := db.DB(ctx).Where("user_id = ?", userID).Find(&accounts).Error; err != nil {
+		return nil, err
+	}
+	return accounts, nil
+}
+
+// UnbindExternalAccount 解绑外部账号
+func UnbindExternalAccount(ctx context.Context, id uint64, userID uint64) error {
+	return db.DB(ctx).Where("id = ? AND user_id = ?", id, userID).Delete(&ExternalAccount{}).Error
+}

backend/plugins/domain/auth/service.go

@@ -0,0 +1,145 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package auth
+
+import (
+	"context"
+	"errors"
+	"sync"
+
+	"github.com/Rain-kl/Wavelet/backend/core/contracts"
+	"github.com/Rain-kl/Wavelet/backend/pkg/util"
+	db "github.com/Rain-kl/Wavelet/backend/plugins/infra/database"
+	"github.com/gin-gonic/gin"
+)
+
+type authServiceImpl struct{}
+
+func newAuthService() contracts.AuthService {
+	return &authServiceImpl{}
+}
+
+func (s *authServiceImpl) RequireAuthMiddleware() any {
+	return LoginRequired()
+}
+
+func (s *authServiceImpl) RequireAdminMiddleware() any {
+	return AdminRequired()
+}
+
+func (s *authServiceImpl) GetCurrentUser(ctx context.Context) (*contracts.UserDTO, error) {
+	if ginCtx, ok := ctx.(*gin.Context); ok {
+		if u, ok := util.GetFromContext[*contracts.UserDTO](ginCtx, contracts.AuthUserObjKey); ok && u != nil {
+			return u, nil
+		}
+	}
+
+	if v := ctx.Value(contracts.AuthUserObjKey); v != nil {
+		if u, ok := v.(*contracts.UserDTO); ok && u != nil {
+			return u, nil
+		}
+	}
+
+	return nil, errors.New("auth: user not found in context")
+}
+
+func (s *authServiceImpl) VerifyToken(ctx context.Context, token string) (*contracts.UserDTO, error) {
+	if token == "" {
+		return nil, errors.New("auth: empty token")
+	}
+
+	tokenHash := hashToken(token)
+	tokenRecord, err := GetCachedToken(ctx, tokenHash)
+	if err != nil {
+		var tokenRow struct {
+			ID      uint64
+			UserID  uint64
+			IsAdmin bool
+		}
+		if err := db.DB(ctx).Table("w_access_tokens").Where("token_hash = ?", tokenHash).First(&tokenRow).Error; err != nil {
+			return nil, err
+		}
+		tokenRecord = &CachedToken{
+			ID:      tokenRow.ID,
+			UserID:  tokenRow.UserID,
+			IsAdmin: tokenRow.IsAdmin,
+		}
+		SetCachedToken(ctx, tokenHash, tokenRecord)
+	}
+
+	user, err := GetCachedUser(ctx, tokenRecord.UserID)
+	if err != nil || user == nil || !user.IsActive {
+		var dbUser contracts.UserDTO
+		if err := db.DB(ctx).Table("w_users").Where("id = ? AND is_active = ?", tokenRecord.UserID, true).First(&dbUser).Error; err != nil {
+			return nil, err
+		}
+		user = &dbUser
+		SetCachedUser(ctx, tokenRecord.UserID, user)
+	}
+
+	if user.Username == SystemUsername {
+		return nil, errors.New("auth: system user token not allowed")
+	}
+
+	return user, nil
+}
+
+func (s *authServiceImpl) CreateSession(_ context.Context, _ uint64, _ map[string]any) (string, error) {
+	return "", nil
+}
+
+func (s *authServiceImpl) RevokeUserSessions(ctx context.Context, userID uint64) error {
+	InvalidateCachedUser(ctx, userID)
+	return nil
+}
+
+func (s *authServiceImpl) GetCurrentUserID(ctx context.Context) (uint64, error) {
+	if ginCtx, ok := ctx.(*gin.Context); ok {
+		return GetUserIDFromContext(ginCtx), nil
+	}
+	return 0, errors.New("auth: user not found in context")
+}
+
+func (s *authServiceImpl) RevokeToken(ctx context.Context, tokenHash string) error {
+	InvalidateCachedToken(ctx, tokenHash)
+	return nil
+}
+
+func (s *authServiceImpl) DisallowTokenAuthMiddleware() any {
+	return DisallowTokenAuth()
+}
+
+type authRegistryImpl struct {
+	mu        sync.RWMutex
+	providers map[string]contracts.OAuthProvider
+}
+
+func newAuthRegistry() contracts.AuthRegistry {
+	return &authRegistryImpl{
+		providers: make(map[string]contracts.OAuthProvider),
+	}
+}
+
+func (r *authRegistryImpl) RegisterOAuthProvider(name string, provider contracts.OAuthProvider) {
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	r.providers[name] = provider
+}
+
+func (r *authRegistryImpl) GetOAuthProvider(name string) (contracts.OAuthProvider, bool) {
+	r.mu.RLock()
+	defer r.mu.RUnlock()
+	p, ok := r.providers[name]
+	return p, ok
+}
+
+func (r *authRegistryImpl) ListOAuthProviders() []string {
+	r.mu.RLock()
+	defer r.mu.RUnlock()
+	res := make([]string, 0, len(r.providers))
+	for name := range r.providers {
+		res = append(res, name)
+	}
+	return res
+}

backend/plugins/domain/auth/session.go

@@ -0,0 +1,145 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package auth
+
+import (
+	"context"
+	"crypto/sha256"
+	"encoding/hex"
+	"net/http"
+	"strconv"
+	"strings"
+
+	"github.com/Rain-kl/Wavelet/backend/core/contracts"
+	"github.com/Rain-kl/Wavelet/backend/pkg/config"
+	db "github.com/Rain-kl/Wavelet/backend/plugins/infra/database"
+	"github.com/gin-contrib/sessions"
+	"github.com/gin-gonic/gin"
+	"github.com/google/uuid"
+	gsessions "github.com/gorilla/sessions"
+)
+
+// GetSessionOptions 根据配置构建 Session 选项
+func GetSessionOptions(maxAge int) sessions.Options {
+	return sessions.Options{
+		Path:     "/",
+		Domain:   config.Config.App.SessionDomain,
+		MaxAge:   maxAge,
+		HttpOnly: config.Config.App.SessionHTTPOnly,
+		Secure:   config.Config.App.SessionSecure,
+		SameSite: http.SameSiteLaxMode,
+	}
+}
+
+// StripCookieMaxAgeAndExpires 从 Set-Cookie 响应头中移除 Max-Age 和 Expires，从而使其成为浏览器会话 Cookie
+func StripCookieMaxAgeAndExpires(header http.Header, cookieName string) {
+	headers := header["Set-Cookie"]
+	if len(headers) == 0 {
+		return
+	}
+
+	newHeaders := make([]string, 0, len(headers))
+	for _, h := range headers {
+		if strings.HasPrefix(h, cookieName+"=") {
+			parts := strings.Split(h, ";")
+			newParts := make([]string, 0, len(parts))
+			for _, p := range parts {
+				trimmed := strings.TrimSpace(p)
+				lower := strings.ToLower(trimmed)
+				if strings.HasPrefix(lower, "max-age=") || strings.HasPrefix(lower, "expires=") {
+					continue
+				}
+				newParts = append(newParts, p)
+			}
+			newHeaders = append(newHeaders, strings.Join(newParts, ";"))
+		} else {
+			newHeaders = append(newHeaders, h)
+		}
+	}
+	header["Set-Cookie"] = newHeaders
+}
+
+// GetUserIDFromSession 从 Session 中提取用户 ID
+func GetUserIDFromSession(s sessions.Session) uint64 {
+	val := s.Get(UserIDKey)
+	return ParseUserID(val)
+}
+
+// GetUserIDFromContext 从 Gin Context 的 Session 中提取用户 ID
+func GetUserIDFromContext(c *gin.Context) (uid uint64) {
+	defer func() {
+		_ = recover()
+	}()
+	session := sessions.Default(c)
+	return GetUserIDFromSession(session)
+}
+
+func ensureSessionToken(s sessions.Session) (string, bool) {
+	token, ok := s.Get(SessionTokenKey).(string)
+	if !ok || token == "" {
+		token = uuid.NewString()
+		s.Set(SessionTokenKey, token)
+		return token, true
+	}
+	return token, false
+}
+
+func hashSessionToken(token string) string {
+	h := sha256.New()
+	h.Write([]byte(token))
+	return hex.EncodeToString(h.Sum(nil))
+}
+
+func rotateSessionID(s sessions.Session) {
+	if inner, ok := s.(interface{ Session() *gsessions.Session }); ok {
+		if sess := inner.Session(); sess != nil {
+			sess.ID = ""
+		}
+	}
+}
+
+// SetLoginSession writes the authenticated user into a freshly rotated session.
+func SetLoginSession(ctx context.Context, c *gin.Context, user *contracts.UserDTO, extras ...map[string]any) error {
+	session := sessions.Default(c)
+	session.Clear()
+	rotateSessionID(session)
+
+	session.Set(UserIDKey, user.ID)
+	session.Set(UserNameKey, user.Username)
+	if len(extras) > 0 {
+		for key, value := range extras[0] {
+			session.Set(key, value)
+		}
+	}
+
+	// 根据系统配置动态设置 Session 过期时间
+	maxAge := config.Config.App.SessionAge
+	isSessionCookie := false
+
+	var val string
+	if err := db.DB(ctx).Table("w_system_configs").Where("key = ?", "login_session_ttl_hours").Pluck("value", &val).Error; err == nil && val != "" {
+		if ttlHours, err := strconv.Atoi(val); err == nil {
+			switch {
+			case ttlHours == -1:
+				// 永不过期，设置为 10 年
+				maxAge = 10 * 365 * 24 * 3600
+			case ttlHours > 0:
+				maxAge = ttlHours * 3600
+			case ttlHours == 0:
+				isSessionCookie = true
+			}
+		}
+	}
+	session.Options(GetSessionOptions(maxAge))
+
+	if err := session.Save(); err != nil {
+		return err
+	}
+
+	if isSessionCookie {
+		StripCookieMaxAgeAndExpires(c.Writer.Header(), config.Config.App.SessionCookieName)
+	}
+
+	return nil
+}