feat(cordis): add OpenFlare Cordis 架构改造设计

docs(changelog): 修正表述笔误

refactor(cordis): 磁盘缓存改用上上游能力并清理本地副本

按上游/下游归属规约：类型断言守卫已回流 Wavelet（f3d85d5，附回归用例），
本仓库删除 OpenFlare/plugins/server/pkg/cache 整包并改 import 到
Wavelet/pkg/cache/disk，同步后与上游零漂移。

验证：go build 通过；go test ./... exit 0（137 包 ok）；256 条路由对拍与
232 条 swagger 操作均零差异；make build-all 四进制；前端零改动。

docs(cordis): 记录 T1 清理结果与五个复用阻塞点

refactor(cordis): server 复用上游 pkg 能力并删除等价本地副本

按上游/下游归属规约清理重复实现，删除 7 个与上游等价的本地包并改 import：
shared/response→pkg/response、pkg/{logger,mail,trace,httppool,cache/ram}→
上游同名包、infra/persistence/batchwriter→pkg/batchwriter。逐项核过差异：
httppool 逐字节相同；logger 的 Config 字段完全一致；response 的 7 个 Abort*
一致；cache/ram 换过去顺带把裸 go 变回带 panic 恢复的 util.Go。

两处非等价差异按语义处理：
- batchwriter.Stats 与 status DTO 原为类型别名，改为消费侧逐字段转换，
  避免 model 反向依赖基础设施类型；
- 上游 pkg/idgen 要求显式 Init（本地副本为懒加载自动初始化），本次保留本地
  副本，待与 infra 初始化一并迁移（已登记在清理计划）。

验证：go build 通过；go test ./... exit 0（138 包 ok）；256 条路由对拍零差异；
make swagger 232 条操作零增减，且归一化后与旧文档深度相等——差异仅为
response.Any / logger.LogEntry 两个定义名随包路径改名，接口形状未变。

chore(cordis): 回流内核与 pkg/util 通用能力并清理 vendoring 污染

按新增的上游/下游归属规约：HandleRaw/BasePath 与版本比较、网络、格式化助手
属通用能力，已提交到 Wavelet 分支 feat/cordis-router-raw-routes，本仓库改为
纯同步获取（pkg/util 已零漂移），补丁登记保留至上游合并。

同时修掉我此前 git add -A 造成的污染：首次 vendoring 把上游工作区里被
gitignore 的运行期产物一起提交进来（upload 的 diskcache 缓存块 650 个与
driver_http/dist 前端构建物 380 个，共 12872 行/1030 文件）。sync-upstream.sh
现显式排除 uploads/dist/data/*.db，.gitignore 补上对应兜底规则。

AGENTS.md 增加上游/下游改动归属规约，并把仍指向前 Cordis 布局的硬性约束
（internal/router + Serve、internal/repository/logstore、internal/platform/bootstrap、
internal/cmd）改到当前插件路径。

验证：go build 通过；go test ./... exit 0（144 包 ok）；make swagger 232 条
操作与基线逐条一致；make build-all 四进制；gofmt 干净。

feat(cordis): server 插件化并改由内核挂载控制面路由

新增 plugins/server/plugin.go：Apply 以 ctx.Router().Group(app.api_prefix)
声明根级与 /v1 全部路由；33 个注册函数由 *gin.RouterGroup 改为
core.RouterExtension，RegisterCollection 改用内核新增的 HandleRaw 保留
尾部斜杠变体，AdminMiddlewares 返回 []any（Go 不允许把 []T 展开为 ...any）。
删除 router.Serve 与 registerRoutes，装配根改为 core.App +
driver_http.New(WithEngine(router.BuildEngine()))，监听、信号与优雅退出归内核；
前端 SPA 的 NoRoute 兜底因内核暂无贡献点而保留在引擎层。

路由保真证据：plugin_parity_test 对拍 baseline/routes-engine.txt 的 256 条
(方法 路径) 零差异；go test ./... exit 0（144 包 ok，含真实 handler 的
openflare/integration 用例走同一条挂载路径）；make swagger 232 条操作与基线
逐条一致；golangci-lint 0 issues；make build-all 四进制；embed_frontend
标签编译通过；前端零改动。

已知待补：带 Redis 的实机 HTTP 冒烟（本机 6379 未启动，session store 与
改造前一样在建店阶段即 fatal），以及 bootstrap 的任务/设置/迁移注册迁入 Apply。

feat(core): RouterExtension 增加 HandleRaw 与 BasePath 以保真尾部斜杠路由

server 插件化的前置：Handle 经 cleanPath 会剥掉尾部斜杠，无法表达
/resource 与 /resource/ 两条不同路由，而 OpenFlare 有 20 个历史 list
端点两者都注册且部署关闭了 RedirectTrailingSlash，缺失即 404。新增
HandleRaw 与 BasePath（作用域包装器同样登记反注册），补 extpoints 用例；
并把 router.Serve 拆出 BuildEngine 以便交给 driver_http.WithEngine 复用，
新增路由表导出 harness，固化 256 条 (方法 路径) 基线供插件化对拍。
上游补丁登记于 backend/OpenFlare/upstream-patches.md，同步脚本改为按目录
前缀输出差异并在同步后提醒确认补丁是否仍在。

验证：go build 通过；go test ./... exit 0（143 包 ok）；gofmt 干净。

docs(cordis): 记录 server 插件接入内核的可行路径与内核能力缺口

feat(cordis): agent/relay/flared 落地为内核驱动插件

三个边缘守护进程各新增 plugin.go，实现 core.Plugin + core.Driver
（自定义 DriverType 与同名 profile），装配与生命周期从 main 迁入
Apply/Start/Stop：Apply 负责 JSON 配置加载、运行环境与用户确保、
openresty/frps/frpc 管理器与各服务装配；Start 以 util.Go 拉起阻塞式
runner 与 GeoIP 周期更新；Stop 收敛主循环结果并在超时时报错而非静默。

入口改为 core.NewApp(core.WithProfile(...)) + Prepare/Run，保持
-config 旗标、默认路径、退出码与启动/停止日志不变。

验证：go build 通过；go test ./... exit 0（143 包 ok，含 3 个插件身份
与配置失败路径测试）；make build-all 四进制产出；三进制实跑缺失配置
均 exit 1 且错误链保留 load {agent,relay,flared} config 原因；gofmt 干净。

refactor(cordis): 按功能职责拆分为 4 个插件与 share 共享层

backend/OpenFlare 不再平铺遗留分层，改为 plugins/{server,agent,relay,flared}
加 share/：控制面业务（openflare/admin/oauth/user/upload/cap/config/health 与
repository/model/infra/router 等支撑层）归 server；三个边缘守护进程各自成插件；
被两个以上插件消费的 protocol/geoip/wsclient/render/pagesarchive/edge 归 share。
同时把 pkg/util 与 buildinfo 合并回上游 pkg（上游已覆盖全部符号，仅 8 个函数与
2 个类型为 OpenFlare 独有，已一并迁入），装配根统一到 backend/cmd（含三个 daemon
入口），Dockerfile 与 release 工作流的构建路径和 -X 注入路径同步更新。

验证：go build 通过；go test ./... exit 0（141 包 ok）；make swagger exit 0 且
232 条 API 操作与基线逐条一致；make build-all 产出 4 进制；-X 注入经二进制
strings 实测生效；日志后端直连门禁改写为按 server 插件业务域扫描并在扫描数为 0
时报错（防门禁静默失效）；前端零改动。

feat(cordis): 落地 backend/share 共享层与上游同步脚本

跨插件共享资源（控制消息协议、GeoIP+iputil、边缘守护进程日志）从下游包
移入 backend/share，并声明其只能依赖 core/pkg 与标准/第三方库，禁止反向
引用下游业务与具体插件实现；新增 scripts/sync-upstream.sh 只覆盖
backend/{core,pkg,plugins}，同步后 --check 报告零差异，证明与上游逐字一致。

go build 通过，go test ./... exit 0（142 包 ok），前端零改动。

refactor(cordis): 采用与 Wavelet 同构的单模块布局并引入上游内核

按上游结构落位：backend/{core,pkg,plugins} 为 Wavelet 上游拷贝，OpenFlare
全部业务收拢到上游 downstream 所对应的位置 backend/OpenFlare/，模块名保持
Wavelet 以保证上游 import 路径逐字一致、同步零改写；三个 daemon 入口移至
backend/OpenFlare/cmd，backend/cmd 与 main.go 作为控制面装配根。

行为不变：go build 通过，142 个测试包全绿（含上游插件测试），232 条 API
操作与改造前逐条一致，四进制产物正常，前端零改动。swagger 暂只扫描下游代码，
待 P4 挂载上游路由后再纳入 plugins/。

style: 修正模块路径改写导致的 import 分组排序漂移

refactor(layout): Go 代码迁入 backend/ 并将模块名简化为 OpenFlare

对齐上游 Wavelet 的仓库布局，为以第二 module 形态 vendoring Cordis 内核与
平台插件做准备：模块路径整体改写为 OpenFlare，Go 目标加 cd backend，
swaggo 产物移至 backend/docs 并把 json/yaml 复制回 docs/ 供站点消费，
Dockerfile 与 release 工作流的构建目录、ldflags 模块路径同步更新。

行为保持不变：232 条路由与改造前逐条一致，95 个测试包全绿，
四进制产物正常，前端零改动。

chore(cordis): 落地改造计划与 schema/路由基线

新增 legacy_dump_test 迁移快照 harness：在临时 sqlite 库上按生产顺序
（goose.UpTo → zone 导入 → goose.Up）跑完 76 个历史迁移并导出 schema 与
版本序列，作为改造前后一致性门禁的唯一事实来源。同时记录 232 条路由清单
与 foundation 实施计划。

docs(cordis): add OpenFlare Cordis 架构改造设计

明确上游以第二 module 形态 vendoring 进 backend/Wavelet、4 个插件
(server/agent/relay/flared) 全部装载内核，并规定保留 76 个历史 goose
迁移 + 一次性版本 stamp 桥接的迁移方案，配套三方 schema 一致性门禁，
确保已部署库不重跑历史、不丢数据。

backend/plugins/domain/auth/audit.go

@@ -0,0 +1,37 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package auth
+
+import (
+	"Wavelet/core/contracts"
+	"Wavelet/pkg/logger"
+	"context"
+	"encoding/json"
+
+	"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,217 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package auth
+
+import (
+	"Wavelet/core/contracts"
+	"context"
+	"errors"
+	"fmt"
+	"strconv"
+	"strings"
+
+	"github.com/coreos/go-oidc/v3/oidc"
+	"golang.org/x/oauth2"
+)
+
+func isOIDCLoginEnabled(ctx context.Context) bool {
+	val, err := GetSystemConfigValue(ctx, "oidc_login_enabled")
+	if 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) {
+	val, err := GetSystemConfigValue(ctx, "server_address")
+	if 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, nonce, 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,116 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package auth
+
+import (
+	"Wavelet/core/contracts"
+	"Wavelet/pkg/cache/ram"
+	"context"
+	"fmt"
+	"time"
+)
+
+const (
+	tokenCacheTTL = 5 * time.Minute
+	userCacheTTL  = 5 * time.Minute
+)
+
+// 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})
+)
+
+func tokenCacheKey(tokenHash string) string {
+	return "oauth:token:" + tokenHash
+}
+
+func userCacheKey(userID uint64) string {
+	return fmt.Sprintf("oauth:user:%d", userID)
+}
+
+// GetCachedToken 获取缓存的 Token
+func GetCachedToken(ctx context.Context, tokenHash string) (*CachedToken, error) {
+	if val, ok := tokenRAM.GetIfPresent(tokenHash); ok {
+		return val, nil
+	}
+
+	if cache := getCache(ctx); cache != nil {
+		var token CachedToken
+		key := tokenCacheKey(tokenHash)
+		if err := cache.Get(ctx, key, &token); err == nil {
+			tokenRAM.Set(tokenHash, &token)
+			return &token, nil
+		}
+	}
+	return nil, fmt.Errorf("cache miss")
+}
+
+// SetCachedToken 设置 Token 缓存
+func SetCachedToken(ctx context.Context, tokenHash string, token *CachedToken) {
+	tokenRAM.Set(tokenHash, token)
+	if cache := getCache(ctx); cache != nil {
+		key := tokenCacheKey(tokenHash)
+		_ = cache.Set(ctx, key, token, tokenCacheTTL)
+	}
+}
+
+// InvalidateCachedToken 吊销/删除 token 缓存
+func InvalidateCachedToken(ctx context.Context, tokenHash string) {
+	tokenRAM.Invalidate(tokenHash)
+	if cache := getCache(ctx); cache != nil {
+		key := tokenCacheKey(tokenHash)
+		_ = cache.Delete(ctx, key)
+	}
+}
+
+// GetCachedUser 获取缓存的 UserDTO
+func GetCachedUser(ctx context.Context, userID uint64) (*contracts.UserDTO, error) {
+	if val, ok := userRAM.GetIfPresent(userID); ok {
+		return val, nil
+	}
+
+	if cache := getCache(ctx); cache != nil {
+		var u contracts.UserDTO
+		key := userCacheKey(userID)
+		if err := cache.Get(ctx, key, &u); err == nil {
+			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) {
+	userRAM.Set(userID, u)
+	if cache := getCache(ctx); cache != nil {
+		key := userCacheKey(userID)
+		_ = cache.Set(ctx, key, u, userCacheTTL)
+	}
+}
+
+// InvalidateCachedUser 吊销/失效 UserDTO 缓存
+func InvalidateCachedUser(ctx context.Context, userID uint64) {
+	userRAM.Invalidate(userID)
+	if cache := getCache(ctx); cache != nil {
+		key := userCacheKey(userID)
+		_ = cache.Delete(ctx, key)
+	}
+}
+
+// StopAuthCacheListener compatibility stub for tests
+func StopAuthCacheListener() {}
+
+// ResetAuthRAMCacheForTest clears only the process-local RAM cache.
+func ResetAuthRAMCacheForTest() {
+	tokenRAM.InvalidateAll()
+	userRAM.InvalidateAll()
+}

backend/plugins/domain/auth/cache_test.go

@@ -0,0 +1,144 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package auth_test
+
+import (
+	"Wavelet/core"
+	"Wavelet/core/contracts"
+	"Wavelet/plugins/domain/auth"
+	"context"
+	"encoding/json"
+	"testing"
+	"time"
+)
+
+type mockCacheService struct {
+	items map[string][]byte
+}
+
+func newMockCacheService() *mockCacheService {
+	return &mockCacheService{items: make(map[string][]byte)}
+}
+
+func (m *mockCacheService) Get(ctx context.Context, key string, target any) error {
+	b, ok := m.items[key]
+	if !ok {
+		return contracts.ErrCacheMiss
+	}
+	return json.Unmarshal(b, target)
+}
+
+func (m *mockCacheService) Set(ctx context.Context, key string, value any, ttl time.Duration) error {
+	b, err := json.Marshal(value)
+	if err != nil {
+		return err
+	}
+	m.items[key] = b
+	return nil
+}
+
+func (m *mockCacheService) Delete(ctx context.Context, key string) error {
+	delete(m.items, key)
+	return nil
+}
+
+func (m *mockCacheService) Invalidate(ctx context.Context, key string) error {
+	return m.Delete(ctx, key)
+}
+
+func (m *mockCacheService) GetOrSet(ctx context.Context, key string, target any, ttl time.Duration, loader func() (any, error)) error {
+	err := m.Get(ctx, key, target)
+	if err == nil {
+		return nil
+	}
+	val, err := loader()
+	if err != nil {
+		return err
+	}
+	if err := m.Set(ctx, key, val, ttl); err != nil {
+		return err
+	}
+	b, _ := json.Marshal(val)
+	return json.Unmarshal(b, target)
+}
+
+func TestTokenCache_GetSetInvalidate(t *testing.T) {
+	ctx := core.NewContext(context.Background())
+	mockCache := newMockCacheService()
+	core.Provide[contracts.CacheService](ctx, mockCache)
+
+	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) {
+	ctx := core.NewContext(context.Background())
+	mockCache := newMockCacheService()
+	core.Provide[contracts.CacheService](ctx, mockCache)
+
+	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/config.go

@@ -0,0 +1,14 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package auth
+
+// SessionConfig defines the session configuration declared by the auth plugin.
+type SessionConfig struct {
+	SessionCookieName string `config:"session_cookie_name" env:"APP_SESSION_COOKIE_NAME" default:"wavelet_session"`
+	SessionSecret     string `config:"session_secret" env:"APP_SESSION_SECRET" secret:"true"`
+	SessionDomain     string `config:"session_domain" env:"APP_SESSION_DOMAIN"`
+	SessionAge        int    `config:"session_age" env:"APP_SESSION_AGE" default:"86400"`
+	SessionHTTPOnly   bool   `config:"session_http_only" env:"APP_SESSION_HTTP_ONLY" default:"true"`
+	SessionSecure     bool   `config:"session_secure" env:"APP_SESSION_SECURE"`
+}

backend/plugins/domain/auth/constants.go

@@ -0,0 +1,39 @@
+// 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,54 @@
+// 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       = "未登录"
+)
+
+// Service 层与鉴权中间件内部错误文案（保持与重构前逐字一致）
+const (
+	errUserNotInContext          = "auth: user not found in context"
+	errEmptyToken                = "auth: empty token"                   //nolint:gosec // false positive: this is an error message, not hardcoded credentials
+	errSystemUserTokenNotAllowed = "auth: system user token not allowed" //nolint:gosec // false positive: this is an error message, not hardcoded credentials
+	errUnauthorizedInternal      = "unauthorized"
+	errSystemUserLoginNotAllowed = "system user is not allowed to login"
+)
+
+// OAuth 回调会话校验错误文案（保持与重构前逐字一致）
+const (
+	errInvalidSessionContext   = "invalid session context"
+	errSessionMismatchForOAuth = "session mismatch for oauth state"
+	errUserContextMismatch     = "user context mismatch for oauth binding"
+)

backend/plugins/domain/auth/handlers.go

@@ -0,0 +1,500 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package auth
+
+import (
+	"Wavelet/core/contracts"
+	"Wavelet/pkg/ginutil"
+	"Wavelet/pkg/idgen"
+	"Wavelet/pkg/logger"
+	"Wavelet/pkg/response"
+	"context"
+	"errors"
+	"fmt"
+	"net/http"
+	"strconv"
+	"strings"
+	"time"
+
+	"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
+	}
+	stateKey := fmt.Sprintf(OAuthStateCacheKeyFormat, state)
+	if cache := getCache(ctx); cache != nil {
+		if err := cache.Set(ctx, stateKey, payloadValue, OAuthStateCacheKeyExpiration); 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 sessionHash == "" {
+		return nil
+	}
+	cache := getCache(ctx)
+	if cache == nil {
+		return nil
+	}
+	key := fmt.Sprintf(oauthStateLimitKeyFormat, sessionHash)
+	var count int
+	_ = cache.Get(ctx, key, &count)
+	count++
+	_ = cache.Set(ctx, key, count, OAuthStateCacheKeyExpiration)
+	if count > 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
+	}
+	stateKey := fmt.Sprintf(OAuthStateCacheKeyFormat, state)
+	if cache := getCache(ctx); cache != nil {
+		if err := cache.Set(ctx, stateKey, payloadValue, OAuthStateCacheKeyExpiration); 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 := fmt.Sprintf(OAuthStateCacheKeyFormat, req.State)
+	var payloadRaw string
+	cache := getCache(ctx)
+	if cache == nil {
+		response.AbortBadRequest(c, errInvalidState)
+		return
+	}
+	if err := cache.Get(ctx, stateKey, &payloadRaw); err != nil {
+		response.AbortBadRequest(c, errInvalidState)
+		return
+	}
+	_ = cache.Delete(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, errInvalidSessionContext)
+		return
+	}
+
+	if hashSessionToken(token) != payload.SessionHash {
+		response.AbortBadRequest(c, errSessionMismatchForOAuth)
+		return
+	}
+
+	if payload.Purpose == OAuthPurposeBind && currentUserID != payload.UserID {
+		response.AbortBadRequest(c, errUserContextMismatch)
+		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
+	}
+	user, err := GetUserByID(ctx, userID)
+	if 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()
+	_ = TouchUserLastLogin(ctx, user.ID, user.LastLoginAt)
+	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:
+		loaded, loadErr := GetUserByID(ctx, account.UserID)
+		if loadErr != nil {
+			response.AbortInternal(c, loadErr.Error())
+			return
+		}
+		user = loaded
+	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()
+	_ = TouchUserLastLogin(ctx, user.ID, user.LastLoginAt)
+	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"
+	}
+
+	existingUsernames, err := ListSimilarUsernames(ctx, base)
+	if 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
+	val, cfgErr := GetSystemConfigValue(ctx, "registration_enabled")
+	if cfgErr == 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 := InsertUser(ctx, &user); 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, _ := ginutil.GetFromContext[*contracts.UserDTO](c, contracts.AuthUserObjKey)
+	session := sessions.Default(c)
+	needChange := session.Get("need_change_password") == true || (user != nil && user.NeedChangePassword)
+
+	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,197 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package auth
+
+import (
+	"Wavelet/core/contracts"
+	"Wavelet/core/extpoints"
+	"Wavelet/pkg/ginutil"
+	"Wavelet/pkg/response"
+	"Wavelet/pkg/trace"
+	"context"
+	"crypto/sha256"
+	"encoding/hex"
+	"errors"
+
+	"github.com/gin-gonic/gin"
+)
+
+// whitelist holds the no-auth route patterns. They are registered during Apply and
+// matched on every request, so PathWhitelist parses them once up front.
+var whitelist = extpoints.NewPathWhitelist()
+
+// RegisterWhitelist registers route patterns that bypass mandatory authentication.
+func RegisterWhitelist(patterns ...string) {
+	whitelist.Add(patterns...)
+}
+
+// IsWhitelisted checks if the specified path matches the auth whitelist.
+func IsWhitelisted(path string) bool {
+	return whitelist.Match(path)
+}
+
+func hashToken(token string) string {
+	h := sha256.New()
+	h.Write([]byte(token))
+	return hex.EncodeToString(h.Sum(nil))
+}
+
+// currentUserIDFromRequestContext 是接入层向 Service 层暴露的登录态桥接。
+//
+// Session 读取必须依赖 *gin.Context，而 Service 层禁止 import gin，
+// 因此该类型断言收敛在本（接入层）文件中。ok 为 false 表示 ctx 不是 *gin.Context。
+func currentUserIDFromRequestContext(ctx context.Context) (uint64, bool) {
+	ginCtx, ok := ctx.(*gin.Context)
+	if !ok {
+		return 0, false
+	}
+	return GetUserIDFromContext(ginCtx), true
+}
+
+func getUserByToken(ctx context.Context, tokenStr string) (*contracts.UserDTO, *CachedToken, error) {
+	tokenHash := hashToken(tokenStr)
+	tokenRecord, err := GetCachedToken(ctx, tokenHash)
+	if err != nil || tokenRecord == nil {
+		tokenRecord, err = GetAccessTokenByHash(ctx, tokenHash)
+		if err != nil {
+			return nil, nil, err
+		}
+		SetCachedToken(ctx, tokenHash, tokenRecord)
+	}
+
+	user, err := GetCachedUser(ctx, tokenRecord.UserID)
+	if err != nil || user == nil || !user.IsActive {
+		user, err = GetActiveUserByID(ctx, tokenRecord.UserID)
+		if err != nil {
+			return nil, nil, err
+		}
+		SetCachedUser(ctx, tokenRecord.UserID, user)
+	}
+
+	return user, tokenRecord, nil
+}
+
+// GetUserFromRequest 从请求中获取当前用户（优先 Access Token，其次 Session）
+func GetUserFromRequest(c *gin.Context) (*contracts.UserDTO, error) {
+	ctx := c.Request.Context()
+	var tokenStr string
+
+	tokenFromQuery := c.Query("token")
+	if tokenFromQuery != "" {
+		tokenStr = tokenFromQuery
+	} else {
+		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(errSystemUserLoginNotAllowed)
+			}
+			ginutil.SetToContext(c, contracts.AuthTokenAuthKey, true)
+			ginutil.SetToContext(c, contracts.AuthTokenAdminKey, tokenRecord.IsAdmin)
+			return user, nil
+		}
+	}
+
+	// 降级使用 Session 鉴权
+	userID := GetUserIDFromContext(c)
+	if userID <= 0 {
+		return nil, errors.New(errUnauthorizedInternal)
+	}
+
+	user, err := GetCachedUser(ctx, userID)
+	if err != nil || user == nil || !user.IsActive {
+		user, err = GetActiveUserByID(ctx, userID)
+		if err != nil {
+			return nil, err
+		}
+		SetCachedUser(ctx, userID, user)
+	}
+
+	ginutil.SetToContext(c, contracts.AuthTokenAuthKey, false)
+	ginutil.SetToContext(c, contracts.AuthTokenAdminKey, false)
+
+	if user.Username == "system" {
+		return nil, errors.New(errSystemUserLoginNotAllowed)
+	}
+
+	return user, nil
+}
+
+// LoginRequired 返回登录鉴权中间件，校验 Access Token 或 Session
+func LoginRequired() gin.HandlerFunc {
+	return func(c *gin.Context) {
+		if IsWhitelisted(c.Request.URL.Path) {
+			c.Next()
+			return
+		}
+
+		_, 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)
+		ginutil.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, _ := ginutil.GetFromContext[bool](c, contracts.AuthTokenAuthKey)
+		isTokenAdmin, _ := ginutil.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)
+		ginutil.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, _ := ginutil.GetFromContext[bool](c, contracts.AuthTokenAuthKey); tokenAuth {
+			response.AbortForbidden(c, ErrTokenAuthNotAllowed)
+			return
+		}
+		c.Next()
+	}
+}

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

@@ -0,0 +1,53 @@
+-- +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,
+    masked_token VARCHAR(64) NOT NULL DEFAULT '',
+    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);
+-- +goose StatementEnd
+
+-- +goose Down
+-- +goose StatementBegin
+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/migrations/sqlite/00001_initial.sql

@@ -0,0 +1,53 @@
+-- +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 0,
+    client_id VARCHAR(255),
+    client_secret VARCHAR(1024),
+    openid_discovery_url VARCHAR(1024),
+    scopes VARCHAR(255),
+    icon_url VARCHAR(1024),
+    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+    updated_at DATETIME 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 DATETIME DEFAULT CURRENT_TIMESTAMP,
+    updated_at DATETIME 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,
+    masked_token VARCHAR(64) NOT NULL DEFAULT '',
+    description VARCHAR(255),
+    is_admin BOOLEAN DEFAULT 0,
+    expires_at DATETIME,
+    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
+);
+CREATE INDEX IF NOT EXISTS idx_w_access_tokens_user_id ON w_access_tokens (user_id);
+-- +goose StatementEnd
+
+-- +goose Down
+-- +goose StatementBegin
+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,241 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package auth
+
+import (
+	"Wavelet/core/contracts"
+	"encoding/json"
+	"errors"
+	"regexp"
+	"strconv"
+	"strings"
+	"time"
+)
+
+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 || user.NeedChangePassword,
+		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,185 @@
+// 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 (
+	"Wavelet/core"
+	"Wavelet/core/contracts"
+	"Wavelet/core/extpoints"
+	"context"
+	"embed"
+	"reflect"
+)
+
+//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"
+}
+
+// Inject declares required dependencies for the auth domain plugin.
+func (p *Plugin) Inject() []reflect.Type {
+	return []reflect.Type{
+		reflect.TypeFor[contracts.DBService](),
+		reflect.TypeFor[contracts.CacheService](),
+	}
+}
+
+// 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",
+	}
+}
+
+// DeclareConfig declares configuration bindings for the auth plugin.
+func (p *Plugin) DeclareConfig() []core.ConfigBinding {
+	return []core.ConfigBinding{
+		{Prefix: "app", Target: &SessionConfig{}},
+	}
+}
+
+// Apply registers the auth migrations, services, routes, and settings into the Context.
+func (p *Plugin) Apply(ctx *core.Context) error {
+	var cfg SessionConfig
+	if err := ctx.Config().Bind("app", &cfg); err == nil {
+		SetSessionConfig(cfg)
+	}
+
+	// 0. Bind DBService & CacheService from Context
+	if db, err := core.Inject[contracts.DBService](ctx); err == nil && db != nil {
+		setDBService(db)
+	} else {
+		core.When[contracts.DBService](ctx, func(db contracts.DBService) {
+			setDBService(db)
+		})
+	}
+	if cache, err := core.Inject[contracts.CacheService](ctx); err == nil && cache != nil {
+		setCacheService(cache)
+	} else {
+		core.When[contracts.CacheService](ctx, func(cache contracts.CacheService) {
+			setCacheService(cache)
+		})
+	}
+	ctx.OnDispose(func() error {
+		setDBService(nil)
+		setCacheService(nil)
+		return nil
+	})
+
+	// 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)
+
+	// 2.1 Register Public / Auth Whitelist Endpoints
+	publicEndpoints := []string{
+		"/api/v1/oauth/sources",
+		"/api/v1/oauth/login",
+		"/api/v1/oauth/*/authorize",
+		"/api/v1/oauth/:source/authorize",
+		"/api/v1/oauth/callback",
+		"/api/v1/user/login",
+		"/api/v1/user/register",
+		"/api/v1/user/send-email-code",
+		"/api/v1/cap/challenge",
+		"/api/v1/cap/redeem",
+		"/healthz",
+		"/metrics",
+	}
+	RegisterWhitelist(publicEndpoints...)
+	ctx.Router().RegisterWhitelist(publicEndpoints...)
+
+	// 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",
+	})
+
+	// 5. Register Event Listeners for domain events
+	ctx.Events().On(contracts.EventTopicUserStatusChanged, func(c context.Context, e contracts.UserStatusChangedEvent) error {
+		InvalidateCachedUser(c, e.UserID)
+		return nil
+	})
+
+	ctx.Events().On(contracts.EventTopicUserDeleted, func(c context.Context, e contracts.UserDeletedEvent) error {
+		InvalidateCachedUser(c, e.TargetUserID)
+		return nil
+	})
+
+	return nil
+}

backend/plugins/domain/auth/plugin_test.go

@@ -0,0 +1,155 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package auth_test
+
+import (
+	"Wavelet/core"
+	"Wavelet/core/contracts"
+	"Wavelet/plugins/domain/auth"
+	"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"
+)
+
+type mockDBService struct {
+	db *gorm.DB
+}
+
+func (m *mockDBService) GORM() *gorm.DB {
+	return m.db
+}
+
+func (m *mockDBService) DB(ctx context.Context) *gorm.DB {
+	return m.db.WithContext(ctx)
+}
+
+func (m *mockDBService) Named(_ string) *gorm.DB {
+	return m.db
+}
+
+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{},
+	))
+
+	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)
+	core.Provide[contracts.DBService](ctx, &mockDBService{db: testDB})
+
+	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,215 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package auth
+
+import (
+	"Wavelet/core"
+	"Wavelet/core/contracts"
+	"Wavelet/pkg/util"
+	"context"
+	"sync"
+	"time"
+
+	"gorm.io/gorm"
+)
+
+var (
+	dbMu     sync.RWMutex
+	dbSvc    contracts.DBService
+	cacheMu  sync.RWMutex
+	cacheSvc contracts.CacheService
+)
+
+func setDBService(s contracts.DBService) {
+	dbMu.Lock()
+	defer dbMu.Unlock()
+	dbSvc = s
+}
+
+func setCacheService(s contracts.CacheService) {
+	cacheMu.Lock()
+	defer cacheMu.Unlock()
+	cacheSvc = s
+}
+
+func getDB(ctx context.Context) *gorm.DB {
+	if c, ok := ctx.(*core.Context); ok && c != nil {
+		if s, err := core.Inject[contracts.DBService](c); err == nil && s != nil {
+			return s.DB(ctx)
+		}
+	}
+	dbMu.RLock()
+	s := dbSvc
+	dbMu.RUnlock()
+	if s != nil {
+		return s.DB(ctx)
+	}
+	return nil
+}
+
+func getCache(ctx context.Context) contracts.CacheService {
+	if c, ok := ctx.(*core.Context); ok && c != nil {
+		if s, err := core.Inject[contracts.CacheService](c); err == nil && s != nil {
+			return s
+		}
+	}
+	cacheMu.RLock()
+	s := cacheSvc
+	cacheMu.RUnlock()
+	return s
+}
+
+// GetAccessTokenByHash 按令牌哈希读取访问令牌记录（仅取鉴权所需字段）
+func GetAccessTokenByHash(ctx context.Context, tokenHash string) (*CachedToken, error) {
+	var row struct {
+		ID      uint64
+		UserID  uint64
+		IsAdmin bool
+	}
+	if err := getDB(ctx).Table("w_access_tokens").Where("token_hash = ?", tokenHash).First(&row).Error; err != nil {
+		return nil, err
+	}
+	return &CachedToken{
+		ID:      row.ID,
+		UserID:  row.UserID,
+		IsAdmin: row.IsAdmin,
+	}, nil
+}
+
+// GetActiveUserByID 读取仍处于启用状态的用户
+func GetActiveUserByID(ctx context.Context, userID uint64) (*contracts.UserDTO, error) {
+	var user contracts.UserDTO
+	if err := getDB(ctx).Table("w_users").Where("id = ? AND is_active = ?", userID, true).First(&user).Error; err != nil {
+		return nil, err
+	}
+	return &user, nil
+}
+
+// GetUserByID 按 ID 读取用户（不限制启用状态）
+func GetUserByID(ctx context.Context, userID uint64) (*contracts.UserDTO, error) {
+	var user contracts.UserDTO
+	if err := getDB(ctx).Table("w_users").Where("id = ?", userID).First(&user).Error; err != nil {
+		return nil, err
+	}
+	return &user, nil
+}
+
+// InsertUser 新建用户记录
+func InsertUser(ctx context.Context, user *contracts.UserDTO) error {
+	return getDB(ctx).Table("w_users").Create(user).Error
+}
+
+// TouchUserLastLogin 刷新用户最后登录时间
+func TouchUserLastLogin(ctx context.Context, userID uint64, at time.Time) error {
+	return getDB(ctx).Table("w_users").Where("id = ?", userID).Update("last_login_at", at).Error
+}
+
+// ListSimilarUsernames 查询与基础用户名相同或带 `-序号` 后缀的用户名（用于用户名去重）
+func ListSimilarUsernames(ctx context.Context, base string) ([]string, error) {
+	var existingUsernames []string
+	if err := getDB(ctx).Table("w_users").
+		Where("username = ? OR username LIKE ? ESCAPE '\\'", base, util.EscapeLike(base)+"-%").
+		Pluck("username", &existingUsernames).Error; err != nil {
+		return nil, err
+	}
+	return existingUsernames, nil
+}
+
+// GetSystemConfigValue 读取系统配置项原始值
+func GetSystemConfigValue(ctx context.Context, key string) (string, error) {
+	var val string
+	if err := getDB(ctx).Table("w_system_configs").Where("key = ?", key).Pluck("value", &val).Error; err != nil {
+		return "", err
+	}
+	return val, nil
+}
+
+// ListAllAuthSources 获取全部认证源（含未启用），按 ID 升序
+func ListAllAuthSources(ctx context.Context) ([]AuthSource, error) {
+	var sources []AuthSource
+	if err := getDB(ctx).Order("id ASC").Find(&sources).Error; err != nil {
+		return nil, err
+	}
+	return sources, nil
+}
+
+// GetAuthSourceByID 根据 ID 获取认证源
+func GetAuthSourceByID(ctx context.Context, id uint64) (*AuthSource, error) {
+	var src AuthSource
+	if err := getDB(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 := getDB(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 := getDB(ctx).Where("is_active = ?", true).Order("id ASC").Find(&sources).Error; err != nil {
+		return nil, err
+	}
+	return sources, nil
+}
+
+// CreateAuthSourceRecord 新建认证源记录
+func CreateAuthSourceRecord(ctx context.Context, source *AuthSource) error {
+	return getDB(ctx).Create(source).Error
+}
+
+// SaveAuthSourceRecord 全量保存认证源记录
+func SaveAuthSourceRecord(ctx context.Context, source *AuthSource) error {
+	return getDB(ctx).Save(source).Error
+}
+
+// DeleteAuthSourceRecord 删除认证源记录
+func DeleteAuthSourceRecord(ctx context.Context, source *AuthSource) error {
+	return getDB(ctx).Delete(source).Error
+}
+
+// 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 := getDB(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 getDB(ctx).Create(account).Error
+}
+
+// ListExternalAccountsByUserID 获取用户绑定的所有外部账号
+func ListExternalAccountsByUserID(ctx context.Context, userID uint64) ([]ExternalAccount, error) {
+	var accounts []ExternalAccount
+	if err := getDB(ctx).Where("user_id = ?", userID).Find(&accounts).Error; err != nil {
+		return nil, err
+	}
+	return accounts, nil
+}
+
+// UnbindExternalAccount 解绑外部账号
+func UnbindExternalAccount(ctx context.Context, id, userID uint64) error {
+	return getDB(ctx).Where("id = ? AND user_id = ?", id, userID).Delete(&ExternalAccount{}).Error
+}

backend/plugins/domain/auth/service.go

@@ -0,0 +1,262 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package auth
+
+import (
+	"Wavelet/core/contracts"
+	"context"
+	"errors"
+	"sync"
+)
+
+type authServiceImpl struct{}
+
+func newAuthService() contracts.AuthService {
+	return &authServiceImpl{}
+}
+
+func (s *authServiceImpl) RequireAuthMiddleware() any {
+	return LoginRequired()
+}
+
+func (s *authServiceImpl) RequireAdminMiddleware() any {
+	return AdminRequired()
+}
+
+// GetCurrentUser 从 context 中读取登录用户。
+//
+// 中间件通过 gin 的 c.Set(contracts.AuthUserObjKey, user) 写入登录态；
+// *gin.Context 自身实现了 context.Context，且其 Value(key) 对 string 类型 key
+// 等价于 c.Get(key)（未命中时再回落到 Request.Context().Value），
+// 因此这里无需感知 gin 即可读取同一份登录态。
+func (s *authServiceImpl) GetCurrentUser(ctx context.Context) (*contracts.UserDTO, error) {
+	if v := ctx.Value(contracts.AuthUserObjKey); v != nil {
+		if u, ok := v.(*contracts.UserDTO); ok && u != nil {
+			return u, nil
+		}
+	}
+
+	return nil, errors.New(errUserNotInContext)
+}
+
+func (s *authServiceImpl) VerifyToken(ctx context.Context, token string) (*contracts.UserDTO, error) {
+	if token == "" {
+		return nil, errors.New(errEmptyToken)
+	}
+
+	tokenHash := hashToken(token)
+	tokenRecord, err := GetCachedToken(ctx, tokenHash)
+	if err != nil {
+		tokenRecord, err = GetAccessTokenByHash(ctx, tokenHash)
+		if err != nil {
+			return nil, err
+		}
+		SetCachedToken(ctx, tokenHash, tokenRecord)
+	}
+
+	user, err := GetCachedUser(ctx, tokenRecord.UserID)
+	if err != nil || user == nil || !user.IsActive {
+		user, err = GetActiveUserByID(ctx, tokenRecord.UserID)
+		if err != nil {
+			return nil, err
+		}
+		SetCachedUser(ctx, tokenRecord.UserID, user)
+	}
+
+	if user.Username == SystemUsername {
+		return nil, errors.New(errSystemUserTokenNotAllowed)
+	}
+
+	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
+}
+
+// GetCurrentUserID 从请求登录态中读取用户 ID。
+//
+// Session 读取依赖 gin，属于接入层职责，因此这里通过接入层桥接函数
+// currentUserIDFromRequestContext（见 middleware.go）取值，Service 层本身不感知 gin。
+func (s *authServiceImpl) GetCurrentUserID(ctx context.Context) (uint64, error) {
+	userID, ok := currentUserIDFromRequestContext(ctx)
+	if !ok {
+		return 0, errors.New(errUserNotInContext)
+	}
+	return userID, nil
+}
+
+func (s *authServiceImpl) RevokeToken(ctx context.Context, tokenHash string) error {
+	InvalidateCachedToken(ctx, tokenHash)
+	return nil
+}
+
+func (s *authServiceImpl) DisallowTokenAuthMiddleware() any {
+	return DisallowTokenAuth()
+}
+
+func (s *authServiceImpl) InvalidateCachedUser(ctx context.Context, userID uint64) {
+	InvalidateCachedUser(ctx, userID)
+}
+
+func (s *authServiceImpl) InvalidateCachedToken(ctx context.Context, tokenHash string) {
+	InvalidateCachedToken(ctx, tokenHash)
+}
+
+func (s *authServiceImpl) ListAuthSources(ctx context.Context) ([]contracts.AuthSourceViewDTO, error) {
+	sources, err := ListAllAuthSources(ctx)
+	if err != nil {
+		return nil, err
+	}
+
+	views := make([]contracts.AuthSourceViewDTO, len(sources))
+	for i := range sources {
+		views[i] = contracts.AuthSourceViewDTO{
+			ID:                     sources[i].ID,
+			Name:                   sources[i].Name,
+			Type:                   sources[i].Type,
+			DisplayName:            sources[i].DisplayName,
+			IsActive:               sources[i].IsActive,
+			IconURL:                sources[i].IconURL,
+			ClientSecretConfigured: sources[i].ClientSecret != "",
+		}
+	}
+	return views, nil
+}
+
+func (s *authServiceImpl) CreateAuthSource(ctx context.Context, source contracts.AuthSourceDTO) (*contracts.AuthSourceDTO, error) {
+	model := AuthSource{
+		ID:                 source.ID,
+		Name:               source.Name,
+		Type:               source.Type,
+		DisplayName:        source.DisplayName,
+		ClientID:           source.ClientID,
+		ClientSecret:       source.ClientSecret,
+		OpenIDDiscoveryURL: source.OpenIDDiscoveryURL,
+		Scopes:             source.Scopes,
+		IconURL:            source.IconURL,
+		IsActive:           source.IsActive,
+	}
+
+	if err := model.Validate(); err != nil {
+		return nil, err
+	}
+
+	if err := CreateAuthSourceRecord(ctx, &model); err != nil {
+		return nil, err
+	}
+
+	model.Sanitize()
+	return toAuthSourceDTO(&model), nil
+}
+
+func (s *authServiceImpl) UpdateAuthSource(ctx context.Context, id uint64, source contracts.AuthSourceDTO) (*contracts.AuthSourceDTO, error) {
+	existing, err := GetAuthSourceByID(ctx, id)
+	if err != nil {
+		return nil, err
+	}
+
+	existing.DisplayName = source.DisplayName
+	existing.ClientID = source.ClientID
+	if source.ClientSecret != "" {
+		existing.ClientSecret = source.ClientSecret
+	}
+	existing.OpenIDDiscoveryURL = source.OpenIDDiscoveryURL
+	existing.Scopes = source.Scopes
+	existing.IconURL = source.IconURL
+
+	if err := existing.Validate(); err != nil {
+		return nil, err
+	}
+
+	if err := SaveAuthSourceRecord(ctx, existing); err != nil {
+		return nil, err
+	}
+
+	existing.Sanitize()
+	return toAuthSourceDTO(existing), nil
+}
+
+func (s *authServiceImpl) DeleteAuthSource(ctx context.Context, id uint64) error {
+	existing, err := GetAuthSourceByID(ctx, id)
+	if err != nil {
+		return err
+	}
+
+	return DeleteAuthSourceRecord(ctx, existing)
+}
+
+func (s *authServiceImpl) ToggleAuthSource(ctx context.Context, id uint64) (*contracts.AuthSourceDTO, error) {
+	existing, err := GetAuthSourceByID(ctx, id)
+	if err != nil {
+		return nil, err
+	}
+
+	existing.IsActive = !existing.IsActive
+	if err := SaveAuthSourceRecord(ctx, existing); err != nil {
+		return nil, err
+	}
+
+	existing.Sanitize()
+	return toAuthSourceDTO(existing), nil
+}
+
+func toAuthSourceDTO(s *AuthSource) *contracts.AuthSourceDTO {
+	if s == nil {
+		return nil
+	}
+	return &contracts.AuthSourceDTO{
+		ID:                 s.ID,
+		Name:               s.Name,
+		Type:               s.Type,
+		DisplayName:        s.DisplayName,
+		ClientID:           s.ClientID,
+		ClientSecret:       s.ClientSecret,
+		OpenIDDiscoveryURL: s.OpenIDDiscoveryURL,
+		Scopes:             s.Scopes,
+		IconURL:            s.IconURL,
+		IsActive:           s.IsActive,
+		CreatedAt:          s.CreatedAt,
+		UpdatedAt:          s.UpdatedAt,
+	}
+}
+
+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/service_test.go

@@ -0,0 +1,401 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package auth_test
+
+import (
+	"Wavelet/core"
+	"Wavelet/core/contracts"
+	"Wavelet/pkg/ginutil"
+	"Wavelet/pkg/response"
+	"Wavelet/plugins/domain/auth"
+	"context"
+	"errors"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/gin-contrib/sessions"
+	"github.com/gin-contrib/sessions/cookie"
+	"github.com/gin-gonic/gin"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"gorm.io/gorm"
+)
+
+const (
+	testSessionCookieName = "auth-test-session"
+	errUserNotInContext   = "auth: user not found in context"
+)
+
+// newTestAuthService 装配仅注册 auth 插件的 core.Context，并返回其对外契约实现。
+func newTestAuthService(t *testing.T, db *gorm.DB) contracts.AuthService {
+	t.Helper()
+
+	ctx := core.NewContext(context.Background())
+	if db != nil {
+		core.Provide[contracts.DBService](ctx, &mockDBService{db: db})
+		core.Provide[contracts.CacheService](ctx, newMockCacheService())
+	}
+	require.NoError(t, auth.New().Apply(ctx))
+
+	svc, err := core.Inject[contracts.AuthService](ctx)
+	require.NoError(t, err)
+	auth.ResetAuthRAMCacheForTest()
+
+	return svc
+}
+
+// newSessionEngine 构造一个带 Session 中间件的 gin 引擎，用于走通真实登录态链路。
+//
+// response.Abort* 只把错误挂载到 gin 错误链，状态码由全局错误中间件渲染，
+// 因此这里必须同时装配 response.ErrorHandlerMiddleware()。
+func newSessionEngine() *gin.Engine {
+	engine := gin.New()
+	engine.Use(response.ErrorHandlerMiddleware())
+	engine.Use(sessions.Sessions(testSessionCookieName, cookie.NewStore([]byte("test-secret"))))
+	return engine
+}
+
+func TestGetCurrentUserFromGinContext(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	svc := newTestAuthService(t, nil)
+	user := &contracts.UserDTO{ID: 4242, Username: "ctx_user", IsActive: true}
+
+	t.Run("gin 上下文已由中间件写入用户时返回该用户", func(t *testing.T) {
+		recorder := httptest.NewRecorder()
+		c, _ := gin.CreateTestContext(recorder)
+		c.Request = httptest.NewRequest(http.MethodGet, "/api/v1/user-info", nil)
+		c.Set(contracts.AuthUserObjKey, user)
+
+		got, err := svc.GetCurrentUser(c)
+		require.NoError(t, err)
+		assert.Same(t, user, got)
+	})
+
+	t.Run("开启 ContextWithFallback 时可从请求 context 回落读取", func(t *testing.T) {
+		// 说明：本项目引擎默认不开启 ContextWithFallback，此时 (*gin.Context).Value
+		// 等价于 c.Get，与改造前 ginutil.GetFromContext 的读取路径完全一致；
+		// 开启回落后还能额外读到写入 Request.Context() 的登录态。
+		reqCtx := context.WithValue(context.Background(), contracts.AuthUserObjKey, user) //nolint:staticcheck // 模拟写入请求 context 的登录态
+		engine := gin.New()
+		engine.ContextWithFallback = true
+		var (
+			gotUser *contracts.UserDTO
+			gotErr  error
+		)
+		engine.GET("/probe", func(c *gin.Context) {
+			gotUser, gotErr = svc.GetCurrentUser(c)
+			c.Status(http.StatusNoContent)
+		})
+
+		engine.ServeHTTP(httptest.NewRecorder(), httptest.NewRequest(http.MethodGet, "/probe", nil).WithContext(reqCtx))
+		require.NoError(t, gotErr)
+		assert.Same(t, user, gotUser)
+	})
+
+	t.Run("未登录时报错且文案不变", func(t *testing.T) {
+		recorder := httptest.NewRecorder()
+		c, _ := gin.CreateTestContext(recorder)
+		c.Request = httptest.NewRequest(http.MethodGet, "/api/v1/user-info", nil)
+
+		got, err := svc.GetCurrentUser(c)
+		require.Error(t, err)
+		assert.Nil(t, got)
+		assert.Equal(t, errUserNotInContext, err.Error())
+	})
+
+	t.Run("非 gin 的普通 context 仍按 Value 取值", func(t *testing.T) {
+		got, err := svc.GetCurrentUser(context.WithValue(context.Background(), contracts.AuthUserObjKey, user)) //nolint:staticcheck // 与中间件写入的 key 语义一致
+		require.NoError(t, err)
+		assert.Same(t, user, got)
+
+		_, err = svc.GetCurrentUser(context.Background())
+		require.Error(t, err)
+		assert.Equal(t, errUserNotInContext, err.Error())
+	})
+}
+
+func TestGetCurrentUserID(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	svc := newTestAuthService(t, nil)
+
+	t.Run("gin Session 中的用户 ID 可正常读取", func(t *testing.T) {
+		engine := newSessionEngine()
+		var (
+			gotUID uint64
+			gotErr error
+		)
+		engine.GET("/probe", func(c *gin.Context) {
+			session := sessions.Default(c)
+			session.Set(auth.UserIDKey, uint64(777))
+			require.NoError(t, session.Save())
+
+			gotUID, gotErr = svc.GetCurrentUserID(c)
+			c.Status(http.StatusNoContent)
+		})
+
+		engine.ServeHTTP(httptest.NewRecorder(), httptest.NewRequest(http.MethodGet, "/probe", nil))
+		require.NoError(t, gotErr)
+		assert.Equal(t, uint64(777), gotUID)
+	})
+
+	t.Run("gin 上下文存在但 Session 无用户时返回 0 且不报错", func(t *testing.T) {
+		engine := newSessionEngine()
+		var (
+			gotUID uint64
+			gotErr error
+		)
+		engine.GET("/probe", func(c *gin.Context) {
+			gotUID, gotErr = svc.GetCurrentUserID(c)
+			c.Status(http.StatusNoContent)
+		})
+
+		engine.ServeHTTP(httptest.NewRecorder(), httptest.NewRequest(http.MethodGet, "/probe", nil))
+		require.NoError(t, gotErr)
+		assert.Equal(t, uint64(0), gotUID)
+	})
+
+	t.Run("非 gin context 报错且文案不变", func(t *testing.T) {
+		// 即使普通 context 中已写入用户对象，该方法的 Session 语义也保持不变。
+		uid, err := svc.GetCurrentUserID(
+			context.WithValue(context.Background(), contracts.AuthUserObjKey, &contracts.UserDTO{ID: 1}), //nolint:staticcheck // 同上
+		)
+		require.Error(t, err)
+		assert.Equal(t, uint64(0), uid)
+		assert.Equal(t, errUserNotInContext, err.Error())
+	})
+}
+
+func TestLoginRequiredMiddlewarePopulatesServiceContext(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+
+	db := setupTestDB(t)
+	require.NoError(t, db.Create(&testUser{ID: 9001, Username: "session_user", IsActive: true}).Error)
+	require.NoError(t, db.Create(&testUser{ID: 9002, Username: "token_user", IsActive: true}).Error)
+
+	tokenStr := "integration-secret-token"
+	require.NoError(t, db.Create(&testAccessToken{
+		ID:        9101,
+		UserID:    9002,
+		TokenHash: hashToken(tokenStr),
+		Name:      "integration",
+		IsAdmin:   false,
+	}).Error)
+
+	svc := newTestAuthService(t, db)
+
+	t.Run("Session 鉴权链路上 GetCurrentUser 与 GetCurrentUserID 一致", func(t *testing.T) {
+		engine := newSessionEngine()
+		engine.Use(func(c *gin.Context) {
+			session := sessions.Default(c)
+			session.Set(auth.UserIDKey, uint64(9001))
+			require.NoError(t, session.Save())
+			c.Next()
+		})
+
+		var (
+			gotUser *contracts.UserDTO
+			userErr error
+			gotUID  uint64
+			uidErr  error
+		)
+		engine.GET("/protected", auth.LoginRequired(), func(c *gin.Context) {
+			gotUser, userErr = svc.GetCurrentUser(c)
+			gotUID, uidErr = svc.GetCurrentUserID(c)
+			c.Status(http.StatusNoContent)
+		})
+
+		recorder := httptest.NewRecorder()
+		engine.ServeHTTP(recorder, httptest.NewRequest(http.MethodGet, "/protected", nil))
+		require.Equal(t, http.StatusNoContent, recorder.Code)
+
+		require.NoError(t, userErr)
+		require.NotNil(t, gotUser)
+		assert.Equal(t, uint64(9001), gotUser.ID)
+		assert.Equal(t, "session_user", gotUser.Username)
+
+		require.NoError(t, uidErr)
+		assert.Equal(t, uint64(9001), gotUID)
+	})
+
+	t.Run("Access Token 鉴权链路上 GetCurrentUser 可用", func(t *testing.T) {
+		engine := newSessionEngine()
+		var (
+			gotUser *contracts.UserDTO
+			userErr error
+		)
+		engine.GET("/protected", auth.LoginRequired(), func(c *gin.Context) {
+			gotUser, userErr = svc.GetCurrentUser(c)
+			c.Status(http.StatusNoContent)
+		})
+
+		req := httptest.NewRequest(http.MethodGet, "/protected", nil)
+		req.Header.Set("Authorization", "Bearer "+tokenStr)
+		recorder := httptest.NewRecorder()
+		engine.ServeHTTP(recorder, req)
+		require.Equal(t, http.StatusNoContent, recorder.Code)
+
+		require.NoError(t, userErr)
+		require.NotNil(t, gotUser)
+		assert.Equal(t, uint64(9002), gotUser.ID)
+		assert.Equal(t, "token_user", gotUser.Username)
+	})
+
+	t.Run("未登录请求被中间件拒绝", func(t *testing.T) {
+		engine := newSessionEngine()
+		engine.GET("/protected", auth.LoginRequired(), func(c *gin.Context) {
+			c.Status(http.StatusNoContent)
+		})
+
+		recorder := httptest.NewRecorder()
+		engine.ServeHTTP(recorder, httptest.NewRequest(http.MethodGet, "/protected", nil))
+		assert.Equal(t, http.StatusUnauthorized, recorder.Code)
+	})
+}
+
+// legacyGetCurrentUser 逐字复刻改造前 Service 层的取值实现
+// （*gin.Context 类型断言 + ginutil.GetFromContext + ctx.Value 回落），
+// 用于与新实现做 differential 等价性校验。
+func legacyGetCurrentUser(ctx context.Context) (*contracts.UserDTO, error) {
+	if ginCtx, ok := ctx.(*gin.Context); ok {
+		if u, ok := ginutil.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(errUserNotInContext)
+}
+
+// legacyGetCurrentUserID 逐字复刻改造前 Service 层基于 gin Session 的实现。
+func legacyGetCurrentUserID(ctx context.Context) (uint64, error) {
+	if ginCtx, ok := ctx.(*gin.Context); ok {
+		return auth.GetUserIDFromContext(ginCtx), nil
+	}
+
+	return 0, errors.New(errUserNotInContext)
+}
+
+func errText(err error) string {
+	if err == nil {
+		return ""
+	}
+	return err.Error()
+}
+
+// assertLoginStateParity 断言新实现与改造前实现在同一 ctx 上返回完全一致的结果与错误文案。
+func assertLoginStateParity(t *testing.T, svc contracts.AuthService, ctx context.Context) {
+	t.Helper()
+
+	wantUser, wantUserErr := legacyGetCurrentUser(ctx)
+	gotUser, gotUserErr := svc.GetCurrentUser(ctx)
+	if (wantUser == nil) != (gotUser == nil) {
+		t.Fatalf("GetCurrentUser nil-ness mismatch: want %v, got %v", wantUser, gotUser)
+	}
+	if wantUser != nil {
+		assert.Same(t, wantUser, gotUser)
+	}
+	assert.Equal(t, errText(wantUserErr), errText(gotUserErr))
+
+	wantUID, wantUIDErr := legacyGetCurrentUserID(ctx)
+	gotUID, gotUIDErr := svc.GetCurrentUserID(ctx)
+	assert.Equal(t, wantUID, gotUID)
+	assert.Equal(t, errText(wantUIDErr), errText(gotUIDErr))
+}
+
+func TestLoginStateContextParityWithLegacyImplementation(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	svc := newTestAuthService(t, nil)
+	user := &contracts.UserDTO{ID: 5150, Username: "parity_user", IsActive: true}
+
+	t.Run("gin 上下文各分支", func(t *testing.T) {
+		recorder := httptest.NewRecorder()
+		c, _ := gin.CreateTestContext(recorder)
+		c.Request = httptest.NewRequest(http.MethodGet, "/api/v1/user-info", nil)
+		assertLoginStateParity(t, svc, c)
+
+		c.Set(contracts.AuthUserObjKey, user)
+		assertLoginStateParity(t, svc, c)
+
+		c.Set(contracts.AuthUserObjKey, "not-a-user-dto")
+		assertLoginStateParity(t, svc, c)
+
+		var typedNil *contracts.UserDTO
+		c.Set(contracts.AuthUserObjKey, typedNil)
+		assertLoginStateParity(t, svc, c)
+	})
+
+	t.Run("普通 context 各分支", func(t *testing.T) {
+		assertLoginStateParity(t, svc, context.Background())
+		assertLoginStateParity(t, svc, context.WithValue(context.Background(), contracts.AuthUserObjKey, user))
+		assertLoginStateParity(t, svc, context.WithValue(context.Background(), contracts.AuthUserObjKey, "nope"))
+	})
+
+	t.Run("Session 登录态各分支", func(t *testing.T) {
+		cases := []struct {
+			name   string
+			userID any
+		}{
+			{name: "无用户", userID: nil},
+			{name: "uint64 用户 ID", userID: uint64(3301)},
+			{name: "float64 用户 ID", userID: float64(3302)},
+			{name: "string 用户 ID", userID: "3303"},
+		}
+
+		for _, tc := range cases {
+			t.Run(tc.name, func(t *testing.T) {
+				engine := newSessionEngine()
+				engine.GET("/probe", func(c *gin.Context) {
+					if tc.userID != nil {
+						session := sessions.Default(c)
+						session.Set(auth.UserIDKey, tc.userID)
+						require.NoError(t, session.Save())
+					}
+					assertLoginStateParity(t, svc, c)
+				})
+
+				engine.ServeHTTP(httptest.NewRecorder(), httptest.NewRequest(http.MethodGet, "/probe", nil))
+			})
+		}
+	})
+}
+
+func TestAuthWhitelistMiddleware(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	ctx := core.NewContext(context.Background())
+	p := auth.New()
+	require.NoError(t, p.Apply(ctx))
+
+	svc, err := core.Inject[contracts.AuthService](ctx)
+	require.NoError(t, err)
+
+	mw, ok := svc.RequireAuthMiddleware().(gin.HandlerFunc)
+	require.True(t, ok)
+
+	engine := newSessionEngine()
+	engine.Use(mw)
+	engine.POST("/api/v1/user/login", func(c *gin.Context) {
+		c.JSON(http.StatusOK, response.OK("login-ok"))
+	})
+	engine.GET("/api/v1/secret-profile", func(c *gin.Context) {
+		c.JSON(http.StatusOK, response.OK("profile-ok"))
+	})
+
+	// 1. Whitelisted route /api/v1/user/login passes through without auth
+	w1 := httptest.NewRecorder()
+	req1, _ := http.NewRequest(http.MethodPost, "/api/v1/user/login", nil)
+	engine.ServeHTTP(w1, req1)
+	assert.Equal(t, http.StatusOK, w1.Code)
+
+	// 2. Non-whitelisted route /api/v1/secret-profile gets 401 Unauthorized
+	w2 := httptest.NewRecorder()
+	req2, _ := http.NewRequest(http.MethodGet, "/api/v1/secret-profile", nil)
+	engine.ServeHTTP(w2, req2)
+	assert.Equal(t, http.StatusUnauthorized, w2.Code)
+}

backend/plugins/domain/auth/session.go

@@ -0,0 +1,169 @@
+// Copyright 2026 Arctel.net
+// SPDX-License-Identifier: Apache-2.0
+
+package auth
+
+import (
+	"Wavelet/core/contracts"
+	"context"
+	"crypto/sha256"
+	"encoding/hex"
+	"net/http"
+	"strconv"
+	"strings"
+	"sync"
+
+	"github.com/gin-contrib/sessions"
+	"github.com/gin-gonic/gin"
+	"github.com/google/uuid"
+	gsessions "github.com/gorilla/sessions"
+)
+
+var (
+	sessConfigMu sync.RWMutex
+	sessConfig   = SessionConfig{
+		SessionCookieName: "wavelet_session",
+		SessionAge:        86400,
+		SessionHTTPOnly:   true,
+	}
+)
+
+// SetSessionConfig updates the active session configuration.
+func SetSessionConfig(cfg SessionConfig) {
+	sessConfigMu.Lock()
+	defer sessConfigMu.Unlock()
+	sessConfig = cfg
+}
+
+// GetSessionConfig returns the active session configuration.
+func GetSessionConfig() SessionConfig {
+	sessConfigMu.RLock()
+	defer sessConfigMu.RUnlock()
+	return sessConfig
+}
+
+// GetSessionOptions 根据配置构建 Session 选项
+func GetSessionOptions(maxAge int) sessions.Options {
+	cfg := GetSessionConfig()
+	return sessions.Options{
+		Path:     "/",
+		Domain:   cfg.SessionDomain,
+		MaxAge:   maxAge,
+		HttpOnly: cfg.SessionHTTPOnly,
+		Secure:   cfg.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 过期时间
+	cfg := GetSessionConfig()
+	maxAge := cfg.SessionAge
+	isSessionCookie := false
+
+	val, err := GetSystemConfigValue(ctx, "login_session_ttl_hours")
+	if 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(), cfg.SessionCookieName)
+	}
+
+	return nil
+}