refactor(aegis): 重构密钥管理 SDK，解耦 Provider/Fetcher/Loader 架构 (#30)

Author: heliannuuthus

aegis/handler.go

@@ -169,7 +169,7 @@ func (h *Handler) GetContext(c *gin.Context) {
 
 	// 获取 AuthFlow（内部会续期内存中的 ExpiresAt）
 	flow := h.authenticateSvc.GetAndValidateFlow(c.Request.Context(), flowID)
-	if flow.HasError() {
+	if flow.Failed() {
 		h.flowErrorResponse(c, flow)
 		return
 	}
@@ -216,7 +216,7 @@ func (h *Handler) GetConnections(c *gin.Context) {
 
 	// 获取 AuthFlow（内部会续期内存中的 ExpiresAt）
 	flow := h.authenticateSvc.GetAndValidateFlow(c.Request.Context(), flowID)
-	if flow.HasError() {
+	if flow.Failed() {
 		h.flowErrorResponse(c, flow)
 		return
 	}
@@ -254,7 +254,7 @@ func (h *Handler) Login(c *gin.Context) {
 
 	// 1. 获取 AuthFlow
 	flow := h.authenticateSvc.GetAndValidateFlow(ctx, flowID)
-	if flow.HasError() {
+	if flow.Failed() {
 		h.flowErrorResponse(c, flow)
 		return
 	}
@@ -406,12 +406,12 @@ func (h *Handler) GetIdentifyContext(c *gin.Context) {
 	ctx := c.Request.Context()
 
 	flow := h.authenticateSvc.GetAndValidateFlow(ctx, flowID)
-	if flow.HasError() {
+	if flow.Failed() {
 		h.flowErrorResponse(c, flow)
 		return
 	}
 
-	if !flow.HasIdentifiedUser() {
+	if !flow.IdentifiedUser() {
 		h.errorResponse(c, autherrors.NewInvalidRequest("no identified user"))
 		return
 	}
@@ -445,7 +445,7 @@ func (h *Handler) ConfirmIdentify(c *gin.Context) {
 	ctx := c.Request.Context()
 
 	flow := h.authenticateSvc.GetAndValidateFlow(ctx, flowID)
-	if flow.HasError() {
+	if flow.Failed() {
 		h.flowErrorResponse(c, flow)
 		return
 	}
@@ -457,7 +457,7 @@ func (h *Handler) ConfirmIdentify(c *gin.Context) {
 		}
 	}()
 
-	if !flow.HasIdentifiedUser() {
+	if !flow.IdentifiedUser() {
 		h.errorResponse(c, autherrors.NewInvalidRequest("no identified user"))
 		return
 	}
@@ -645,21 +645,21 @@ func (h *Handler) UserInfo(c *gin.Context) {
 	}
 
 	uat := tc.UserAccessToken()
-	if uat == nil || !uat.HasUser() {
+	if uat == nil || !uat.Identified() {
 		c.JSON(http.StatusUnauthorized, gin.H{
 			"error":             "invalid_token",
 			"error_description": "token does not contain user info",
 		})
 		return
 	}
 
-	email := uat.GetEmail()
-	phone := uat.GetPhone()
+	email := uat.Email()
+	phone := uat.Phone()
 
 	resp := &UserInfoResponse{
-		Sub:           uat.GetOpenID(),
-		Nickname:      uat.GetNickname(),
-		Picture:       uat.GetPicture(),
+		Sub:           uat.OpenID(),
+		Nickname:      uat.Nickname(),
+		Picture:       uat.Picture(),
 		Email:         helpers.MaskEmail(email),
 		EmailVerified: email != "",
 		Phone:         helpers.MaskPhone(phone),

aegis/init.go

@@ -51,8 +51,6 @@ func Initialize(hermesSvc *hermes.Service, userSvc *hermes.UserService, credenti
 	cacheManager := cache.NewManager(hermesSvc, userSvc, redis)
 
 	// 3. 初始化 KeyStore
-	watcher := key.NewSimpleWatcher()
-
 	ssoMasterKeyFetcher := func() ([][]byte, error) {
 		masterKey, err := config.GetSSOMasterKey()
 		if err != nil {
@@ -65,7 +63,7 @@ func Initialize(hermesSvc *hermes.Service, userSvc *hermes.UserService, credenti
 	}
 
 	// 域密钥：clientID → domain.Main（id="aegis" 时返回 SSO master key）
-	domainKeyStore := key.NewNamedStore("domain", key.FetcherFunc(func(ctx context.Context, clientID string) ([][]byte, error) {
+	domainKeyProvider := key.LoadKeysFunc(func(ctx context.Context, clientID string) ([][]byte, error) {
 		if clientID == token.SSOIssuer {
 			return ssoMasterKeyFetcher()
 		}
@@ -78,10 +76,10 @@ func Initialize(hermesSvc *hermes.Service, userSvc *hermes.UserService, credenti
 			return nil, fmt.Errorf("get domain: %w", err)
 		}
 		return [][]byte{domain.Main}, nil
-	}), watcher)
+	})
 
 	// 服务密钥：audience → service.Key（id="aegis" 时返回 SSO master key）
-	serviceKeyStore := key.NewNamedStore("service", key.FetcherFunc(func(ctx context.Context, audience string) ([][]byte, error) {
+	serviceKeyProvider := key.LoadKeysFunc(func(ctx context.Context, audience string) ([][]byte, error) {
 		if audience == token.SSOAudience {
 			return ssoMasterKeyFetcher()
 		}
@@ -90,19 +88,19 @@ func Initialize(hermesSvc *hermes.Service, userSvc *hermes.UserService, credenti
 			return nil, fmt.Errorf("get service: %w", err)
 		}
 		return [][]byte{svc.Key}, nil
-	}), watcher)
+	})
 
 	// 应用密钥：clientID → app.Key
-	appKeyStore := key.NewNamedStore("app", key.FetcherFunc(func(ctx context.Context, clientID string) ([][]byte, error) {
+	appKeyProvider := key.LoadKeysFunc(func(ctx context.Context, clientID string) ([][]byte, error) {
 		app, err := cacheManager.GetApplication(ctx, clientID)
 		if err != nil {
 			return nil, fmt.Errorf("get application: %w", err)
 		}
 		return [][]byte{app.Key}, nil
-	}), watcher)
+	})
 
 	// 4. 初始化 Token Service
-	tokenSvc := token.NewService(cacheManager, domainKeyStore, serviceKeyStore, appKeyStore)
+	tokenSvc := token.NewService(cacheManager, domainKeyProvider, serviceKeyProvider, appKeyProvider)
 	logger.Info("[Auth] Token Service 初始化完成")
 
 	// 4. 初始化邮件发送器

aegis/internal/token/service.go

@@ -6,6 +6,8 @@ import (
 	"fmt"
 	"sync"
 
+	"aidanwoods.dev/go-paseto"
+
 	"github.com/heliannuuthus/helios/aegis/config"
 	"github.com/heliannuuthus/helios/aegis/internal/cache"
 	"github.com/heliannuuthus/helios/pkg/aegis/key"
@@ -19,9 +21,9 @@ type Service struct {
 	issuer string
 	cache  *cache.Manager
 
-	domainKeyStore  *key.Store // clientID → domain.Main (includes SSO with id="aegis")
-	serviceKeyStore *key.Store // audience → service.Key (includes SSO with id="aegis")
-	appKeyStore     *key.Store // clientID → app.Key
+	domainKeyProvider  key.Provider // clientID → domain.Main (includes SSO with id="aegis")
+	serviceKeyProvider key.Provider // audience → service.Key (includes SSO with id="aegis")
+	appKeyProvider     key.Provider // clientID → app.Key
 
 	domainSigners     map[string]*Signer
 	domainVerifiers   map[string]*pkgtoken.Verifier
@@ -33,21 +35,21 @@ type Service struct {
 
 func NewService(
 	cache *cache.Manager,
-	domainKeyStore *key.Store,
-	serviceKeyStore *key.Store,
-	appKeyStore *key.Store,
+	domainKeyProvider key.Provider,
+	serviceKeyProvider key.Provider,
+	appKeyProvider key.Provider,
 ) *Service {
 	return &Service{
-		issuer:            config.GetIssuer(),
-		cache:             cache,
-		domainKeyStore:    domainKeyStore,
-		serviceKeyStore:   serviceKeyStore,
-		appKeyStore:       appKeyStore,
-		domainSigners:     make(map[string]*Signer),
-		domainVerifiers:   make(map[string]*pkgtoken.Verifier),
-		serviceEncryptors: make(map[string]*Encryptor),
-		serviceDecryptors: make(map[string]*pkgtoken.Decryptor),
-		appVerifiers:      make(map[string]*pkgtoken.Verifier),
+		issuer:             config.GetIssuer(),
+		cache:              cache,
+		domainKeyProvider:  domainKeyProvider,
+		serviceKeyProvider: serviceKeyProvider,
+		appKeyProvider:     appKeyProvider,
+		domainSigners:      make(map[string]*Signer),
+		domainVerifiers:    make(map[string]*pkgtoken.Verifier),
+		serviceEncryptors:  make(map[string]*Encryptor),
+		serviceDecryptors:  make(map[string]*pkgtoken.Decryptor),
+		appVerifiers:       make(map[string]*pkgtoken.Verifier),
 	}
 }
 
@@ -131,14 +133,12 @@ func (s *Service) Verify(ctx context.Context, tokenString string) (Token, error)
 		if err != nil {
 			logger.Warnf("failed to get audience from token: %v", err)
 		}
-		claimsJSON, err := s.serviceDecryptor(audience).Decrypt(ctx, encryptedSub)
+		innerToken, err := s.serviceDecryptor(audience).Decrypt(ctx, encryptedSub)
 		if err != nil {
 			return nil, fmt.Errorf("decrypt sub: %w", err)
 		}
 
-		if err := s.unmarshalPayload(t, claimsJSON); err != nil {
-			return nil, fmt.Errorf("unmarshal payload: %w", err)
-		}
+		s.applyPayload(t, innerToken)
 	}
 
 	return t, nil
@@ -161,7 +161,7 @@ func (s *Service) domainSigner(clientID string) *Signer {
 		return signer
 	}
 
-	signer = NewSigner(s.domainKeyStore, clientID)
+	signer = NewSigner(s.domainKeyProvider, clientID)
 	s.domainSigners[clientID] = signer
 	return signer
 }
@@ -181,7 +181,7 @@ func (s *Service) domainVerifier(clientID string) *pkgtoken.Verifier {
 		return verifier
 	}
 
-	verifier = pkgtoken.NewVerifier(s.domainKeyStore, clientID)
+	verifier = pkgtoken.NewVerifier(s.domainKeyProvider, clientID)
 	s.domainVerifiers[clientID] = verifier
 	return verifier
 }
@@ -201,7 +201,7 @@ func (s *Service) serviceEncryptor(audience string) *Encryptor {
 		return encryptor
 	}
 
-	encryptor = NewEncryptor(s.serviceKeyStore, audience)
+	encryptor = NewEncryptor(s.serviceKeyProvider, audience)
 	s.serviceEncryptors[audience] = encryptor
 	return encryptor
 }
@@ -221,7 +221,7 @@ func (s *Service) serviceDecryptor(audience string) *pkgtoken.Decryptor {
 		return decryptor
 	}
 
-	decryptor = pkgtoken.NewDecryptor(s.serviceKeyStore, audience)
+	decryptor = pkgtoken.NewDecryptor(s.serviceKeyProvider, audience)
 	s.serviceDecryptors[audience] = decryptor
 	return decryptor
 }
@@ -241,7 +241,7 @@ func (s *Service) appVerifier(clientID string) *pkgtoken.Verifier {
 		return verifier
 	}
 
-	verifier = pkgtoken.NewVerifier(s.appKeyStore, clientID)
+	verifier = pkgtoken.NewVerifier(s.appKeyProvider, clientID)
 	s.appVerifiers[clientID] = verifier
 	return verifier
 }
@@ -252,16 +252,16 @@ func (s *Service) appVerifier(clientID string) *pkgtoken.Verifier {
 func (*Service) marshalPayload(t tokendef.Token) ([]byte, bool) {
 	switch v := t.(type) {
 	case *tokendef.UserAccessToken:
-		if !v.HasUser() {
+		if !v.Identified() {
 			return nil, false
 		}
-		data, err := v.MarshalUserPayload()
+		data, err := v.MarshalIdentity()
 		if err != nil {
 			return nil, false
 		}
 		return data, true
 	case *SSOToken:
-		if !v.HasUser() {
+		if v.GetIdentities() == nil {
 			return nil, false
 		}
 		data, err := v.MarshalIdentities()
@@ -278,24 +278,11 @@ func (*Service) needsDecryption(tokenType tokendef.TokenType) bool {
 	return tokenType == tokendef.TokenTypeUAT || tokenType == tokendef.TokenTypeSSO
 }
 
-// unmarshalPayload decrypts and sets the payload on UAT and SSO tokens.
-func (*Service) unmarshalPayload(t tokendef.Token, data []byte) error {
+func (*Service) applyPayload(t tokendef.Token, inner *paseto.Token) {
 	switch v := t.(type) {
 	case *tokendef.UserAccessToken:
-		info, err := tokendef.UnmarshalUserInfo(data)
-		if err != nil {
-			return err
-		}
-		v.SetUserInfo(info)
-		return nil
+		v.SetIdentity(inner)
 	case *SSOToken:
-		identities, err := UnmarshalIdentities(data)
-		if err != nil {
-			return err
-		}
-		v.SetIdentities(identities)
-		return nil
-	default:
-		return fmt.Errorf("token type %s does not support payload decryption", t.Type())
+		v.SetIdentities(inner)
 	}
 }

aegis/internal/token/sso.go

@@ -87,14 +87,17 @@ func (s *SSOToken) MarshalIdentities() ([]byte, error) {
 	return json.Marshal(s.identities)
 }
 
-func (s *SSOToken) SetIdentities(identities map[string]string) {
+func (s *SSOToken) SetIdentities(t *paseto.Token) {
+	claims := t.Claims()
+	identities := make(map[string]string, len(claims))
+	for k, v := range claims {
+		if str, ok := v.(string); ok {
+			identities[k] = str
+		}
+	}
 	s.identities = identities
 }
 
-func (s *SSOToken) HasUser() bool {
-	return len(s.identities) > 0
-}
-
 func (s *SSOToken) GetOpenID(domain string) string {
 	if s.identities == nil {
 		return ""
@@ -125,12 +128,3 @@ func ParseSSOToken(pasetoToken *paseto.Token) (*SSOToken, error) {
 		Claims: claims,
 	}, nil
 }
-
-// UnmarshalIdentities deserializes identity mapping from decrypted inner token claims.
-func UnmarshalIdentities(data []byte) (map[string]string, error) {
-	var identities map[string]string
-	if err := json.Unmarshal(data, &identities); err != nil {
-		return nil, fmt.Errorf("unmarshal identities: %w", err)
-	}
-	return identities, nil
-}

aegis/internal/types/authflow.go

@@ -362,8 +362,8 @@ func (f *AuthFlow) AllRequiredVerified() bool {
 	return true
 }
 
-// HasIdentifiedUser 是否存在待关联的已有用户（User 已设但 State 仍为 Initialized）
-func (f *AuthFlow) HasIdentifiedUser() bool {
+// IdentifiedUser 是否存在待关联的已有用户（User 已设但 State 仍为 Initialized）
+func (f *AuthFlow) IdentifiedUser() bool {
 	return f.User != nil && f.State == FlowStateInitialized
 }
 
@@ -416,8 +416,8 @@ func (f *AuthFlow) Fail(err AuthErrorInterface) {
 	}
 }
 
-// HasError 检查是否有错误
-func (f *AuthFlow) HasError() bool {
+// Failed 检查流程是否失败
+func (f *AuthFlow) Failed() bool {
 	return f.Error != nil || f.State == FlowStateFailed
 }
 

aegis/middleware/auth.go

@@ -60,15 +60,15 @@ func OptionalToken(v *web.Interpreter) gin.HandlerFunc {
 	}
 }
 
-// NewHermesKeyStore 创建 Hermes 使用的 KeyStore
-func NewHermesKeyStore() (*key.Store, error) {
+// NewHermesKeyProvider 创建 Hermes 使用的密钥 Provider
+func NewHermesKeyProvider() (key.Provider, error) {
 	masterKey, err := hermesconfig.GetAegisSecretKeyBytes()
 	if err != nil {
 		return nil, fmt.Errorf("get hermes aegis secret key: %w", err)
 	}
-	return key.NewStore(key.FetcherFunc(func(ctx context.Context, id string) ([][]byte, error) {
-		return [][]byte{masterKey}, nil
-	}), nil), nil
+	return key.LoadKeyFunc(func(_ context.Context, _ string) ([]byte, error) {
+		return masterKey, nil
+	}), nil
 }
 
 func tokenPreview(tokenStr string, length int) string {