@stackonward/cli 0.0.1 → 1.0.0

package/dist/resources/templates/go-backend/internal/common/middleware/apikey_auth.go

@@ -0,0 +1,320 @@
+package middleware
+
+import (
+	"context"
+	"encoding/json"
+	"net"
+	"strings"
+	"time"
+
+	"github.com/gin-gonic/gin"
+	"go.uber.org/zap"
+
+	"{{module}}/internal/common/types"
+	"{{module}}/pkg/apierror"
+)
+
+// ═══════════════════════════════════════════════════════════════
+// API Key 验证接口（在 middleware 包定义，避免循环依赖）
+// ═══════════════════════════════════════════════════════════════
+
+// APIKeyVerifier API Key 验证器接口
+//
+// 由 apikey 模块的 Service 实现，middleware 仅依赖此接口。
+type APIKeyVerifier interface {
+	// VerifyKey 验证 API Key 并返回密钥信息
+	VerifyKey(ctx context.Context, rawKey string) (*APIKeyInfo, error)
+	// IsBruteForceBlocked 检查 IP 是否被暴力破解封锁
+	IsBruteForceBlocked(ctx context.Context, ip string) bool
+	// RecordInvalidAttempt 记录无效的 API Key 尝试
+	RecordInvalidAttempt(ctx context.Context, ip string)
+	// RecordUsage 异步记录 API Key 用量统计（fire-and-forget）
+	RecordUsage(ctx context.Context, keyID int64, statusCode int, latencyMs int)
+}
+
+// APIKeyInfo API Key 信息（middleware 内部使用）
+type APIKeyInfo struct {
+	// KeyID 密钥 ID
+	KeyID int64
+	// UserID 所属用户 ID
+	UserID int64
+	// ProductCode 产品标识码
+	ProductCode string
+	// Scopes 权限范围
+	Scopes []string
+	// IPWhitelist IP 白名单
+	IPWhitelist []string
+	// RateLimitTier 限流层级
+	RateLimitTier string
+}
+
+// API Key 上下文键
+const (
+	apiKeyIDKey          = "__apiKeyID"
+	apiKeyUserIDKey      = "__apiKeyUserID"
+	apiKeyScopesKey      = "__apiKeyScopes"
+	apiKeyTierKey        = "__apiKeyTier"
+	apiKeyProductCodeKey = "__apiKeyProductCode"
+)
+
+// APIKeyAuth API Key 认证中间件
+//
+// 从 Authorization header 或 X-API-Key header 中提取 API Key，
+// 验证有效性，检查 IP 白名单，注入 API Key 上下文信息。
+// 支持与 GatewayIdentity 共存：请求中没有 API Key 则跳过。
+func APIKeyAuth(verifier APIKeyVerifier, logger *zap.Logger) gin.HandlerFunc {
+	if logger == nil {
+		logger = zap.NewNop()
+	}
+
+	return func(c *gin.Context) {
+		// 提取 API Key
+		rawKey := extractAPIKey(c)
+		if rawKey == "" {
+			// 没有 API Key，跳过（可能使用 Session/JWT 认证）
+			c.Next()
+			return
+		}
+
+		// 验证密钥前缀格式
+		if !strings.HasPrefix(rawKey, "onex_") {
+			abortWithAPIError(c, apierror.Unauthorized("Invalid API key format"))
+			return
+		}
+
+		// 暴力破解防护
+		clientIP := c.ClientIP()
+		if verifier.IsBruteForceBlocked(c.Request.Context(), clientIP) {
+			abortWithAPIError(c, apierror.Unauthorized("Too many invalid attempts, try again later"))
+			return
+		}
+
+		// 验证密钥
+		keyInfo, err := verifier.VerifyKey(c.Request.Context(), rawKey)
+		if err != nil {
+			verifier.RecordInvalidAttempt(c.Request.Context(), clientIP)
+			abortWithAPIError(c, apierror.Unauthorized("Invalid or expired API key"))
+			return
+		}
+
+		// IP 白名单检查
+		if !checkAPIKeyIPWhitelist(keyInfo.IPWhitelist, clientIP) {
+			logger.Warn("api key ip not in whitelist",
+				zap.Int64("keyId", keyInfo.KeyID),
+				zap.String("clientIP", clientIP),
+			)
+			abortWithAPIError(c, apierror.Forbidden("IP address not allowed for this API key"))
+			return
+		}
+
+		// 注入 API Key 上下文
+		c.Set(apiKeyIDKey, keyInfo.KeyID)
+		c.Set(apiKeyUserIDKey, keyInfo.UserID)
+		c.Set(apiKeyScopesKey, keyInfo.Scopes)
+		c.Set(apiKeyTierKey, keyInfo.RateLimitTier)
+		c.Set(apiKeyProductCodeKey, keyInfo.ProductCode)
+
+		// 同时注入 UserIdentity，让下游业务侧可以统一通过 GetUserIdentity / GetUserID 获取主体。
+		// API Key 走 user.id（业务侧），不绑定 identity_id（auth domain 内部主键）；
+		// 因此 IdentityID 留空（IsZero），auth-source 中间件会跳过这类请求。
+		c.Set(string(types.ContextKeyUserIdentity), &types.UserIdentity{
+			UserID: types.UserID(keyInfo.UserID),
+			Type:   "user",
+		})
+
+		// 设置调试用响应头
+		c.Header("X-API-Key-ID", strings.Repeat("*", 6))
+
+		// 记录请求开始时间，用于计算延迟
+		start := time.Now()
+
+		c.Next()
+
+		// 请求完成后异步记录用量统计
+		// 使用 context.Background() 而非请求 context，避免请求取消导致用量丢失
+		statusCode := c.Writer.Status()
+		latencyMs := int(time.Since(start).Milliseconds())
+		go verifier.RecordUsage(context.Background(), keyInfo.KeyID, statusCode, latencyMs)
+	}
+}
+
+// RequireScope 权限范围校验中间件
+//
+// 必须在 APIKeyAuth 之后使用。检查 API Key 的 Scopes 是否包含
+// 所需的权限。支持精确匹配和层级匹配（write 包含 read）。
+func RequireScope(requiredScope string) gin.HandlerFunc {
+	return func(c *gin.Context) {
+		scopesRaw, exists := c.Get(apiKeyScopesKey)
+		if !exists {
+			// 非 API Key 认证的请求，跳过 Scope 检查
+			c.Next()
+			return
+		}
+
+		scopes, ok := scopesRaw.([]string)
+		if !ok {
+			// 尝试从 JSON 解析
+			if jsonScopes, jsonOK := scopesRaw.(json.RawMessage); jsonOK {
+				var parsed []string
+				if err := json.Unmarshal(jsonScopes, &parsed); err == nil {
+					scopes = parsed
+					ok = true
+				}
+			}
+		}
+
+		if !ok {
+			abortWithAPIError(c, apierror.Forbidden("Invalid API key scopes"))
+			return
+		}
+
+		if !hasScope(scopes, requiredScope) {
+			abortWithAPIError(c, apierror.Forbidden(
+				"API key does not have required scope: "+requiredScope))
+			return
+		}
+
+		c.Next()
+	}
+}
+
+// extractAPIKey 从请求中提取 API Key
+func extractAPIKey(c *gin.Context) string {
+	// 1. Authorization: Bearer <key>
+	auth := c.GetHeader("Authorization")
+	if strings.HasPrefix(auth, "Bearer ") {
+		token := strings.TrimPrefix(auth, "Bearer ")
+		if strings.HasPrefix(token, "onex_") {
+			return token
+		}
+	}
+
+	// 2. X-API-Key: <key>
+	apiKey := c.GetHeader("X-API-Key")
+	if apiKey != "" {
+		return apiKey
+	}
+
+	return ""
+}
+
+// checkAPIKeyIPWhitelist 检查客户端 IP 是否在白名单中
+func checkAPIKeyIPWhitelist(whitelist []string, clientIP string) bool {
+	// 空白名单表示不限制
+	if len(whitelist) == 0 {
+		return true
+	}
+
+	ip := net.ParseIP(clientIP)
+	if ip == nil {
+		return false
+	}
+
+	for _, allowed := range whitelist {
+		// 尝试 CIDR 匹配
+		if strings.Contains(allowed, "/") {
+			_, cidr, err := net.ParseCIDR(allowed)
+			if err == nil && cidr.Contains(ip) {
+				return true
+			}
+		}
+		// 精确 IP 匹配
+		if allowed == clientIP {
+			return true
+		}
+	}
+
+	return false
+}
+
+// hasScope 检查权限是否满足
+func hasScope(scopes []string, required string) bool {
+	for _, s := range scopes {
+		// 精确匹配
+		if s == required {
+			return true
+		}
+		// 层级匹配：admin 包含所有权限
+		if s == "admin" {
+			return true
+		}
+		// write 包含 read（通用级别和资源级别）
+		if s == "write" && (required == "read" || strings.HasSuffix(required, ":read")) {
+			return true
+		}
+		// 资源级匹配：conversations:write 包含 conversations:read
+		if strings.HasSuffix(s, ":write") && strings.HasSuffix(required, ":read") {
+			sResource := strings.TrimSuffix(s, ":write")
+			rResource := strings.TrimSuffix(required, ":read")
+			if sResource == rResource {
+				return true
+			}
+		}
+	}
+	return false
+}
+
+// GetAPIKeyID 从上下文获取 API Key ID
+func GetAPIKeyID(c *gin.Context) int64 {
+	v, ok := c.Get(apiKeyIDKey)
+	if !ok {
+		return 0
+	}
+	id, ok := v.(int64)
+	if !ok {
+		return 0
+	}
+	return id
+}
+
+// GetAPIKeyUserID 从上下文获取 API Key 所属用户 ID
+func GetAPIKeyUserID(c *gin.Context) int64 {
+	v, ok := c.Get(apiKeyUserIDKey)
+	if !ok {
+		return 0
+	}
+	id, ok := v.(int64)
+	if !ok {
+		return 0
+	}
+	return id
+}
+
+// GetAPIKeyTier 从上下文获取 API Key 限流层级
+func GetAPIKeyTier(c *gin.Context) string {
+	v, ok := c.Get(apiKeyTierKey)
+	if !ok {
+		return ""
+	}
+	tier, ok := v.(string)
+	if !ok {
+		return ""
+	}
+	return tier
+}
+
+// GetAPIKeyScopes 从上下文获取 API Key 权限范围
+func GetAPIKeyScopes(c *gin.Context) []string {
+	v, ok := c.Get(apiKeyScopesKey)
+	if !ok {
+		return nil
+	}
+	scopes, ok := v.([]string)
+	if !ok {
+		return nil
+	}
+	return scopes
+}
+
+// GetAPIKeyProductCode 从上下文获取 API Key 产品标识
+func GetAPIKeyProductCode(c *gin.Context) string {
+	v, ok := c.Get(apiKeyProductCodeKey)
+	if !ok {
+		return ""
+	}
+	code, ok := v.(string)
+	if !ok {
+		return ""
+	}
+	return code
+}

package/dist/resources/templates/go-backend/internal/common/middleware/apikey_throttle.go

@@ -0,0 +1,158 @@
+package middleware
+
+import (
+	"context"
+	"fmt"
+	"strconv"
+	"time"
+
+	"github.com/gin-gonic/gin"
+	"go.uber.org/zap"
+
+	"{{module}}/internal/common/types"
+	"{{module}}/pkg/apierror"
+)
+
+// ═══════════════════════════════════════════════════════════════
+// API Key 限流接口（在 middleware 包定义，避免循环依赖）
+// ═══════════════════════════════════════════════════════════════
+
+// APIKeyRateLimiter API Key 限流器接口
+//
+// 由 apikey 模块的 Service 实现，middleware 仅依赖此接口。
+type APIKeyRateLimiter interface {
+	// CheckLimit 检查 API Key 是否超限
+	//
+	// 按多窗口策略（分钟、小时、天）分别检查，任一窗口超限即拒绝。
+	// 返回最紧迫窗口的限流结果。userID 用于超限事件中标识触发用户。
+	CheckLimit(ctx context.Context, keyID int64, userID int64, productCode, tier string) (*APIKeyRateLimitResult, error)
+}
+
+// APIKeyRateLimitResult API Key 限流检查结果
+type APIKeyRateLimitResult struct {
+	// Allowed 是否允许请求
+	Allowed bool
+	// Limit 最紧迫窗口的请求上限
+	Limit int
+	// Remaining 最紧迫窗口的剩余请求次数
+	Remaining int
+	// ResetAt 最紧迫窗口的重置时间
+	ResetAt time.Time
+	// Window 最紧迫窗口的类型
+	Window string
+	// Windows 各窗口详细结果
+	Windows []*WindowCheckResult
+}
+
+// WindowCheckResult 单窗口限流检查结果
+type WindowCheckResult struct {
+	// Window 窗口类型（minute/hour/day）
+	Window string
+	// Limit 窗口上限
+	Limit int
+	// Remaining 剩余请求次数
+	Remaining int
+	// ResetAt 重置时间
+	ResetAt time.Time
+}
+
+// APIKeyThrottle API Key 多窗口限流中间件
+//
+// 必须在 APIKeyAuth 之后使用。从上下文中获取 API Key ID 和 Tier，
+// 查询限流策略，对每个时间窗口分别执行滑动窗口算法。
+// 所有窗口都通过才允许请求，返回最紧迫窗口的限流头。
+//
+// 设计原则：
+//   - Redis 不可用时放行（Fail-Open），优先保障业务可用性
+//   - 非 API Key 认证的请求直接跳过
+//   - 限流头始终返回（无论是否被限流），方便客户端感知配额状态
+func APIKeyThrottle(limiter APIKeyRateLimiter, logger *zap.Logger) gin.HandlerFunc {
+	if logger == nil {
+		logger = zap.NewNop()
+	}
+
+	return func(c *gin.Context) {
+		keyID := GetAPIKeyID(c)
+		if keyID == 0 {
+			// 非 API Key 认证的请求，跳过
+			c.Next()
+			return
+		}
+
+		// 获取限流参数
+		userID := GetAPIKeyUserID(c)
+		tier := GetAPIKeyTier(c)
+		productCode := GetAPIKeyProductCode(c)
+		if productCode == "" {
+			productCode = string(GetProductCode(c))
+		}
+		if productCode == "" {
+			productCode = "platform"
+		}
+
+		// 执行限流检查
+		result, err := limiter.CheckLimit(c.Request.Context(), keyID, userID, productCode, tier)
+		if err != nil {
+			// Redis 不可用或策略查询失败时放行（Fail-Open）
+			logger.Warn("api key rate limit check failed, allowing request",
+				zap.Error(err),
+				zap.Int64("keyId", keyID),
+			)
+			c.Next()
+			return
+		}
+
+		// 设置限流响应头
+		setAPIKeyRateLimitHeaders(c, result)
+
+		if !result.Allowed {
+			apiErr := apierror.TooManyRequests()
+			c.AbortWithStatusJSON(apiErr.Status, apiErr.ToResponse())
+			return
+		}
+
+		c.Next()
+	}
+}
+
+// setAPIKeyRateLimitHeaders 设置多窗口限流响应头
+//
+// 标准头使用最紧迫窗口的数据，扩展头展示各窗口详情。
+func setAPIKeyRateLimitHeaders(c *gin.Context, result *APIKeyRateLimitResult) {
+	if result == nil {
+		return
+	}
+
+	// 标准限流头（使用最紧迫的窗口）
+	c.Header(types.HeaderRateLimitLimit, strconv.Itoa(result.Limit))
+	c.Header(types.HeaderRateLimitRemaining, strconv.Itoa(result.Remaining))
+	c.Header(types.HeaderRateLimitReset, strconv.FormatInt(result.ResetAt.Unix(), 10))
+
+	// 扩展头：各窗口详情
+	for _, w := range result.Windows {
+		prefix := fmt.Sprintf("X-RateLimit-%s", capitalizeWindow(w.Window))
+		c.Header(prefix+"-Limit", strconv.Itoa(w.Limit))
+		c.Header(prefix+"-Remaining", strconv.Itoa(w.Remaining))
+	}
+
+	// 被限流时设置 Retry-After
+	if !result.Allowed {
+		retryAfter := result.ResetAt.Unix() - time.Now().Unix()
+		if retryAfter < 1 {
+			retryAfter = 1
+		}
+		c.Header(types.HeaderRetryAfter, strconv.FormatInt(retryAfter, 10))
+	}
+}
+
+// capitalizeWindow 将窗口类型首字母大写
+func capitalizeWindow(s string) string {
+	if s == "" {
+		return s
+	}
+	first := s[0]
+	if first >= 'a' && first <= 'z' {
+		return string(first-32) + s[1:]
+	}
+	return s
+}

package/dist/resources/templates/go-backend/internal/common/middleware/auth.go

@@ -0,0 +1,40 @@
+package middleware
+
+import (
+	"github.com/gin-gonic/gin"
+
+	"{{module}}/pkg/apierror"
+)
+
+const apiErrorWriterContextKey = "__apiErrorWriter"
+
+// APIErrorWriter 定义单个 HTTP 边界的错误线协议写入策略。
+type APIErrorWriter func(*gin.Context, *apierror.APIError)
+
+// UseAPIErrorWriter 为当前路由组选择明确的错误线协议。
+func UseAPIErrorWriter(writer APIErrorWriter) gin.HandlerFunc {
+	if writer == nil {
+		panic("API error writer is required")
+	}
+	return func(c *gin.Context) {
+		c.Set(apiErrorWriterContextKey, writer)
+		c.Next()
+	}
+}
+
+// WriteAPIError 使用当前路由组选择的策略写入 APIError。
+func WriteAPIError(c *gin.Context, apiErr *apierror.APIError) {
+	if value, exists := c.Get(apiErrorWriterContextKey); exists {
+		if writer, ok := value.(APIErrorWriter); ok {
+			writer(c, apiErr)
+			return
+		}
+	}
+	c.JSON(apiErr.Status, apiErr.ToResponse())
+}
+
+// abortWithAPIError 终止请求并返回 APIError 响应
+func abortWithAPIError(c *gin.Context, apiErr *apierror.APIError) {
+	WriteAPIError(c, apiErr)
+	c.Abort()
+}

package/dist/resources/templates/go-backend/internal/common/middleware/auth_test.go

@@ -0,0 +1,50 @@
+package middleware
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/gin-gonic/gin"
+	"github.com/stretchr/testify/require"
+
+	"{{module}}/pkg/apierror"
+)
+
+func TestWriteAPIErrorUsesCanonicalEnvelopeByDefault(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	recorder := httptest.NewRecorder()
+	context, _ := gin.CreateTestContext(recorder)
+
+	WriteAPIError(context, apierror.BadRequest(apierror.CodeInvalidOperation, "Invalid product"))
+
+	require.Equal(t, http.StatusBadRequest, recorder.Code)
+	require.JSONEq(t, `{
+		"error": {
+			"type": "invalid_request_error",
+			"code": "invalid_operation",
+			"message": "Invalid product"
+		}
+	}`, recorder.Body.String())
+}
+
+func TestUseAPIErrorWriterSelectsExplicitBoundaryProtocol(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	router := gin.New()
+	legacy := router.Group("/legacy")
+	legacy.Use(UseAPIErrorWriter(func(c *gin.Context, apiErr *apierror.APIError) {
+		c.JSON(apiErr.Status, struct {
+			Code string `json:"code"`
+		}{Code: apiErr.Detail.Code})
+	}))
+	legacy.GET("/resource", func(c *gin.Context) {
+		WriteAPIError(c, apierror.BadRequest(apierror.CodeInvalidOperation, "Invalid product"))
+	})
+
+	recorder := httptest.NewRecorder()
+	request := httptest.NewRequest(http.MethodGet, "/legacy/resource", nil)
+	router.ServeHTTP(recorder, request)
+
+	require.Equal(t, http.StatusBadRequest, recorder.Code)
+	require.JSONEq(t, `{"code":"invalid_operation"}`, recorder.Body.String())
+}

package/dist/resources/templates/go-backend/internal/common/middleware/client_context.go

@@ -0,0 +1,86 @@
+package middleware
+
+import (
+	"strconv"
+	"strings"
+
+	"github.com/gin-gonic/gin"
+
+	"{{module}}/internal/common/types"
+)
+
+// ClientContext 从请求 Header 中提取客户端上下文信息
+// 包括客户端类型、版本、平台和真实 IP
+func ClientContext() gin.HandlerFunc {
+	return func(c *gin.Context) {
+		clientIP := ResolveTrustedClientIP(c)
+
+		version := strings.TrimSpace(c.GetHeader(types.HeaderClientVersion))
+		if version == "" {
+			version = strings.TrimSpace(c.GetHeader(types.HeaderAppVersion))
+		}
+
+		ctx := &types.ClientContext{
+			Type:                  strings.TrimSpace(c.GetHeader(types.HeaderClientType)),
+			Version:               version,
+			Platform:              strings.TrimSpace(c.GetHeader(types.HeaderClientPlatform)),
+			DeviceID:              strings.TrimSpace(c.GetHeader(types.HeaderDeviceID)),
+			IP:                    clientIP,
+			AcceptLanguage:        strings.TrimSpace(c.GetHeader("Accept-Language")),
+			Locale:                strings.TrimSpace(c.GetHeader(types.HeaderClientLocale)),
+			Timezone:              strings.TrimSpace(c.GetHeader(types.HeaderClientTimezone)),
+			TimezoneOffsetMinutes: parseOptionalIntHeader(c, types.HeaderClientTimezoneOffset),
+			ScreenWidth:           parseOptionalIntHeader(c, types.HeaderClientScreenWidth),
+			ScreenHeight:          parseOptionalIntHeader(c, types.HeaderClientScreenHeight),
+			ViewportWidth:         parseOptionalIntHeader(c, types.HeaderClientViewportWidth),
+			ViewportHeight:        parseOptionalIntHeader(c, types.HeaderClientViewportHeight),
+			ColorDepth:            parseOptionalIntHeader(c, types.HeaderClientColorDepth),
+			PixelRatio:            parseOptionalFloatHeader(c, types.HeaderClientPixelRatio),
+			TouchPoints:           parseOptionalIntHeader(c, types.HeaderClientTouchPoints),
+			JavaEnabled:           parseOptionalBoolHeader(c, types.HeaderClientJavaEnabled),
+			JavaScriptEnabled:     parseOptionalBoolHeader(c, types.HeaderClientJavaScriptEnabled),
+			CookiesEnabled:        parseOptionalBoolHeader(c, types.HeaderClientCookiesEnabled),
+			GeoCountryCode:        strings.TrimSpace(c.GetHeader(types.HeaderGeoIPCountryCode)),
+			GeoCity:               strings.TrimSpace(c.GetHeader(types.HeaderGeoIPCity)),
+		}
+
+		c.Set(string(types.ContextKeyClientContext), ctx)
+		c.Next()
+	}
+}
+
+func parseOptionalIntHeader(c *gin.Context, header string) *int {
+	raw := strings.TrimSpace(c.GetHeader(header))
+	if raw == "" {
+		return nil
+	}
+	value, err := strconv.Atoi(raw)
+	if err != nil {
+		return nil
+	}
+	return &value
+}
+
+func parseOptionalFloatHeader(c *gin.Context, header string) *float64 {
+	raw := strings.TrimSpace(c.GetHeader(header))
+	if raw == "" {
+		return nil
+	}
+	value, err := strconv.ParseFloat(raw, 64)
+	if err != nil {
+		return nil
+	}
+	return &value
+}
+
+func parseOptionalBoolHeader(c *gin.Context, header string) *bool {
+	raw := strings.TrimSpace(c.GetHeader(header))
+	if raw == "" {
+		return nil
+	}
+	value, err := strconv.ParseBool(raw)
+	if err != nil {
+		return nil
+	}
+	return &value
+}