优化结构

2026-08-23 00:38:33 +08:00
parent 64459574b2
commit 4e5071ee65
22 changed files with 301 additions and 127 deletions
@@ -0,0 +1,9 @@
+# Internal Security
+
+This package owns the application's administrator JWT policy. It is kept
+inside `internal` because its claims, audience, issuer and password-version
+fields are KRA-specific security protocol, not a reusable JWT utility.
+
+Generic stateless helpers may live in `pkg`, but admin token signing and
+verification stay here so other services cannot accidentally depend on this
+application's security contract.
@@ -7,7 +7,11 @@ import (
 	"github.com/golang-jwt/jwt/v5"
 )

+const TokenAudience = "KRA"
+
 var (
+	ErrEmptySigningKey       = errors.New("empty JWT signing key")
+	ErrInvalidClaims         = errors.New("invalid token claims")
 	ErrTokenExpired          = errors.New("token expired")
 	ErrTokenMalformed        = errors.New("token malformed")
 	ErrTokenSignatureInvalid = errors.New("token signature invalid")
@@ -29,29 +33,54 @@ type Claims struct {
 }

 func Generate(secret, issuer string, expires, buffer time.Duration, userID, authorityID uint, uuid, username, nickname string, mustChange bool, passwordVersion int64) (string, *Claims, error) {
-	if secret == "" {
-		return "", nil, errors.New("empty JWT signing key")
+	if err := validateSigningOptions(secret, expires, buffer); err != nil {
+		return "", nil, err
 	}
 	now := time.Now()
-	claims := &Claims{UUID: uuid, ID: userID, Username: username, NickName: nickname, AuthorityID: authorityID, BufferTime: int64(buffer / time.Second), UserType: "admin", MustChangePwd: mustChange, PasswordVersion: passwordVersion, RegisteredClaims: jwt.RegisteredClaims{Audience: jwt.ClaimStrings{"KRA"}, Issuer: issuer, IssuedAt: jwt.NewNumericDate(now), NotBefore: jwt.NewNumericDate(now.Add(-1000)), ExpiresAt: jwt.NewNumericDate(now.Add(expires))}}
+	claims := &Claims{UUID: uuid, ID: userID, Username: username, NickName: nickname, AuthorityID: authorityID, BufferTime: int64(buffer / time.Second), UserType: "admin", MustChangePwd: mustChange, PasswordVersion: passwordVersion, RegisteredClaims: jwt.RegisteredClaims{Audience: jwt.ClaimStrings{TokenAudience}, Issuer: issuer, IssuedAt: jwt.NewNumericDate(now), NotBefore: jwt.NewNumericDate(now.Add(-time.Second)), ExpiresAt: jwt.NewNumericDate(now.Add(expires))}}
 	token, err := Sign(secret, claims)
 	return token, claims, err
 }

 func Sign(secret string, claims *Claims) (string, error) {
 	if secret == "" {
-		return "", errors.New("empty JWT signing key")
+		return "", ErrEmptySigningKey
+	}
+	if claims == nil {
+		return "", ErrInvalidClaims
 	}
 	return jwt.NewWithClaims(jwt.SigningMethodHS256, claims).SignedString([]byte(secret))
 }

 func Parse(tokenString, secret string) (*Claims, error) {
+	return parse(tokenString, secret, "")
+}
+
+// ParseWithIssuer validates a KRA admin token and its configured issuer.
+func ParseWithIssuer(tokenString, secret, issuer string) (*Claims, error) {
+	return parse(tokenString, secret, issuer)
+}
+
+func parse(tokenString, secret, issuer string) (*Claims, error) {
+	if secret == "" {
+		return nil, ErrEmptySigningKey
+	}
+	options := []jwt.ParserOption{
+		jwt.WithValidMethods([]string{jwt.SigningMethodHS256.Alg()}),
+		jwt.WithAudience(TokenAudience),
+		jwt.WithExpirationRequired(),
+		jwt.WithNotBeforeRequired(),
+		jwt.WithLeeway(time.Second),
+	}
+	if issuer != "" {
+		options = append(options, jwt.WithIssuer(issuer))
+	}
 	token, err := jwt.ParseWithClaims(tokenString, &Claims{}, func(token *jwt.Token) (any, error) {
 		if token.Method != jwt.SigningMethodHS256 {
 			return nil, errors.New("unexpected signing method")
 		}
 		return []byte(secret), nil
-	})
+	}, options...)
 	if err != nil {
 		switch {
 		case errors.Is(err, jwt.ErrTokenExpired):
@@ -71,7 +100,20 @@ func Parse(tokenString, secret string) (*Claims, error) {
 	}
 	claims, ok := token.Claims.(*Claims)
 	if !ok {
-		return nil, errors.New("token claims are invalid")
+		return nil, ErrInvalidClaims
 	}
 	return claims, nil
 }
+
+func validateSigningOptions(secret string, expires, buffer time.Duration) error {
+	if secret == "" {
+		return ErrEmptySigningKey
+	}
+	if expires <= 0 {
+		return errors.New("JWT expiration must be positive")
+	}
+	if buffer < 0 {
+		return errors.New("JWT buffer must not be negative")
+	}
+	return nil
+}
@@ -0,0 +1,75 @@
+package security
+
+import (
+	"errors"
+	"testing"
+	"time"
+
+	"github.com/golang-jwt/jwt/v5"
+)
+
+func TestGenerateAndParseWithIssuerRoundTrip(t *testing.T) {
+	token, want, err := Generate("secret", "kra-admin", time.Hour, time.Minute, 7, 8, "uuid", "alice", "Alice", true, 9)
+	if err != nil {
+		t.Fatal(err)
+	}
+	got, err := ParseWithIssuer(token, "secret", "kra-admin")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got.ID != want.ID || got.Username != want.Username || got.Audience[0] != TokenAudience {
+		t.Fatalf("claims = %#v, want %#v", got, want)
+	}
+}
+
+func TestParseRejectsWrongIssuerAndAudience(t *testing.T) {
+	token, _, err := Generate("secret", "kra-admin", time.Hour, time.Minute, 1, 1, "uuid", "user", "", false, 0)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, err = ParseWithIssuer(token, "secret", "other"); !errors.Is(err, ErrTokenInvalid) {
+		t.Fatalf("wrong issuer error = %v, want ErrTokenInvalid", err)
+	}
+	claims := &Claims{RegisteredClaims: jwt.RegisteredClaims{Audience: jwt.ClaimStrings{"other"}, Issuer: "kra-admin", IssuedAt: jwt.NewNumericDate(time.Now()), NotBefore: jwt.NewNumericDate(time.Now().Add(-time.Second)), ExpiresAt: jwt.NewNumericDate(time.Now().Add(time.Hour))}}
+	token, err = Sign("secret", claims)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, err = ParseWithIssuer(token, "secret", "kra-admin"); !errors.Is(err, ErrTokenInvalid) {
+		t.Fatalf("wrong audience error = %v, want ErrTokenInvalid", err)
+	}
+}
+
+func TestParseRejectsMissingRequiredTimeClaims(t *testing.T) {
+	claims := &Claims{RegisteredClaims: jwt.RegisteredClaims{Audience: jwt.ClaimStrings{TokenAudience}, Issuer: "kra-admin"}}
+	token, err := Sign("secret", claims)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, err = ParseWithIssuer(token, "secret", "kra-admin"); !errors.Is(err, ErrTokenInvalid) {
+		t.Fatalf("missing time claims error = %v, want ErrTokenInvalid", err)
+	}
+}
+
+func TestSigningOptionsRejectInvalidValues(t *testing.T) {
+	if _, _, err := Generate("", "kra", time.Hour, 0, 1, 1, "", "", "", false, 0); !errors.Is(err, ErrEmptySigningKey) {
+		t.Fatalf("empty key error = %v", err)
+	}
+	if _, _, err := Generate("secret", "kra", 0, 0, 1, 1, "", "", "", false, 0); err == nil {
+		t.Fatal("zero expiration was accepted")
+	}
+	if _, err := Sign("secret", nil); !errors.Is(err, ErrInvalidClaims) {
+		t.Fatalf("nil claims error = %v", err)
+	}
+}
+
+func TestParseRejectsAlgorithmConfusion(t *testing.T) {
+	claims := &Claims{RegisteredClaims: jwt.RegisteredClaims{Audience: jwt.ClaimStrings{TokenAudience}, Issuer: "kra-admin", IssuedAt: jwt.NewNumericDate(time.Now()), NotBefore: jwt.NewNumericDate(time.Now().Add(-time.Second)), ExpiresAt: jwt.NewNumericDate(time.Now().Add(time.Hour))}}
+	token, err := jwt.NewWithClaims(jwt.SigningMethodHS512, claims).SignedString([]byte("secret"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, err = ParseWithIssuer(token, "secret", "kra-admin"); !errors.Is(err, ErrTokenSignatureInvalid) {
+		t.Fatalf("algorithm confusion error = %v, want ErrTokenSignatureInvalid", err)
+	}
+}