@stackonward/cli 0.0.1 → 1.0.0

package/dist/resources/templates/go-backend/internal/common/providerconfig/schema_test.go

@@ -0,0 +1,47 @@
+package providerconfig
+
+import (
+	"encoding/json"
+	"encoding/pem"
+	"errors"
+	"testing"
+)
+
+func TestValidateConfigurationCanonicalizesSharedValueClasses(t *testing.T) {
+	minimum := int64(1)
+	maximum := int64(5)
+	privateKey := string(pem.EncodeToMemory(&pem.Block{Type: "PRIVATE KEY", Bytes: []byte{1, 2, 3}}))
+	fields := []Field{
+		{Key: "endpoint", Label: "Endpoint", ValueType: ValueTypeString, Required: true, Validation: FieldValidation{Format: ValidationFormatURL}},
+		{Key: "retries", Label: "Retries", ValueType: ValueTypeInteger, Validation: FieldValidation{MinValue: &minimum, MaxValue: &maximum}},
+		{Key: "credentials", Label: "Credentials", ValueType: ValueTypeJSON, Required: true, Secret: true, Sensitive: true, Validation: FieldValidation{RequiredJSONKeys: []string{"client_email", "private_key"}}},
+		{Key: "private_key", Label: "Private Key", ValueType: ValueTypeString, Required: true, Secret: true, Sensitive: true, Validation: FieldValidation{Format: ValidationFormatPEM}},
+	}
+	validated, err := ValidateConfiguration(fields, map[string]string{
+		"credentials": ` { "private_key": "value", "client_email": "service@example.com" } `,
+		"private_key": "  " + privateKey + "  ",
+	}, json.RawMessage(`{"endpoint":" https://example.com ","retries":3}`), ValidationOptions{RequireRequired: true})
+	if err != nil {
+		t.Fatalf("validate configuration: %v", err)
+	}
+	if string(validated.Config) != `{"endpoint":"https://example.com","retries":3}` {
+		t.Fatalf("canonical config = %s", validated.Config)
+	}
+	if validated.Secrets["credentials"] != `{"client_email":"service@example.com","private_key":"value"}` {
+		t.Fatalf("canonical JSON secret = %q", validated.Secrets["credentials"])
+	}
+	if validated.Secrets["private_key"] != privateKey {
+		t.Fatal("PEM secret was not canonicalized")
+	}
+}
+
+func TestValidateConfigurationReturnsStructuredInputError(t *testing.T) {
+	_, err := ValidateConfiguration([]Field{{Key: "api_key", Label: "API Key", ValueType: ValueTypeString, Secret: true}}, nil, json.RawMessage(`{"unknown":true}`), ValidationOptions{})
+	var inputErr *InputError
+	if !errors.As(err, &inputErr) {
+		t.Fatalf("error = %T %v, want InputError", err, err)
+	}
+	if inputErr.Source != InputSourceConfig || inputErr.Field != "unknown" || inputErr.Problem != "is not defined" {
+		t.Fatalf("input error = %+v", inputErr)
+	}
+}

package/dist/resources/templates/go-backend/internal/common/requestprivacy/request.go

@@ -0,0 +1,246 @@
+package requestprivacy
+
+import (
+	"net/http"
+	"net/url"
+	"strings"
+
+	commontypes "{{module}}/internal/common/types"
+)
+
+const (
+	redactedValue       = "redacted"
+	redactedHeaderValue = "[REDACTED]"
+	// UnmatchedRoute 是未命中已注册路由时的低基数遥测路径。
+	UnmatchedRoute = "/unmatched"
+)
+
+// QueryValuePolicy 定义请求 URL 查询值进入日志或遥测前的处理策略。
+type QueryValuePolicy func(string) string
+
+var sensitiveQueryKeys = map[string]struct{}{
+	"access_token":         {},
+	"api_key":              {},
+	"apikey":               {},
+	"authorization":        {},
+	"callback_url":         {},
+	"cancel_url":           {},
+	"client_secret":        {},
+	"code":                 {},
+	"code_verifier":        {},
+	"credential":           {},
+	"csrf_token":           {},
+	"device_id":            {},
+	"email":                {},
+	"id_token":             {},
+	"identity_id":          {},
+	"key":                  {},
+	"launch_code":          {},
+	"mfa_token":            {},
+	"nonce":                {},
+	"otp":                  {},
+	"password":             {},
+	"payment_result_token": {},
+	"phone":                {},
+	"phone_number":         {},
+	"proof":                {},
+	"purchase_token":       {},
+	"q":                    {},
+	"query":                {},
+	"redirect_uri":         {},
+	"refresh_token":        {},
+	"recovery_code":        {},
+	"reset_token":          {},
+	"return_state":         {},
+	"return_url":           {},
+	"session_token":        {},
+	"secret":               {},
+	"signature":            {},
+	"state":                {},
+	"success_url":          {},
+	"token":                {},
+	"unsubscribe_token":    {},
+	"user_id":              {},
+	"verification_code":    {},
+	"verifier":             {},
+}
+
+var sensitivePathParameterPredecessors = map[string]struct{}{
+	"by-token":        {},
+	"devices":         {},
+	"payment-results": {},
+	"unsubscribe":     {},
+}
+
+var sensitiveHeaderNames = map[string]struct{}{
+	"api-key":                 {},
+	"authorization":           {},
+	"baggage":                 {},
+	"cookie":                  {},
+	"idempotency-key":         {},
+	"mcp-session-id":          {},
+	"paypal-request-id":       {},
+	"paypal-transmission-sig": {},
+	"proxy-authorization":     {},
+	"set-cookie":              {},
+	"sign":                    {},
+	"stripe-signature":        {},
+	"wechatpay-signature":     {},
+	"x-amz-security-token":    {},
+	"x-anonymous-session-id":  {},
+	"x-api-key":               {},
+	"x-auth-token":            {},
+	normalizeHeaderName(commontypes.HeaderCheckoutReturnState):  {},
+	normalizeHeaderName(commontypes.HeaderCheckoutSessionToken): {},
+	"x-csrf-token":             {},
+	"x-goog-iap-jwt-assertion": {},
+	normalizeHeaderName(commontypes.HeaderIdentityID):          {},
+	normalizeHeaderName(commontypes.HeaderIdempotencyKey):      {},
+	normalizeHeaderName(commontypes.HeaderInternalUserID):      {},
+	"x-onex-delegated-authority":                               {},
+	normalizeHeaderName(commontypes.HeaderOneXGuestCapability): {},
+	"x-onex-signature":         {},
+	"x-onex-webhook-signature": {},
+	"x-oss-signature":          {},
+	"x-preview-token":          {},
+	normalizeHeaderName(commontypes.HeaderSessionID):    {},
+	normalizeHeaderName(commontypes.HeaderTokenJTI):     {},
+	"x-twilio-signature":                                {},
+	normalizeHeaderName(commontypes.HeaderUserID):       {},
+	normalizeHeaderName(commontypes.HeaderUserPublicID): {},
+	"x-webhook-secret":                                  {},
+	"x-webhook-signature":                               {},
+	"x-hub-signature-256":                               {},
+	"x-signature":                                       {},
+	"x-widget-app-key":                                  {},
+	"x-widget-session-uid":                              {},
+}
+
+// SanitizeURL 复制并清理 URL，优先使用低基数路由模板并移除用户信息、RawPath 和片段。
+func SanitizeURL(source *url.URL, routeTemplate string, queryPolicy QueryValuePolicy) url.URL {
+	if source == nil {
+		return url.URL{}
+	}
+	sanitized := *source
+	sanitized.User = nil
+	sanitized.Opaque = ""
+	sanitized.Path = SanitizePath(source.Path, routeTemplate)
+	sanitized.RawPath = ""
+	sanitized.RawQuery = SanitizeQuery(source.RawQuery, queryPolicy)
+	sanitized.ForceQuery = false
+	sanitized.Fragment = ""
+	sanitized.RawFragment = ""
+	return sanitized
+}
+
+// SanitizeRawURL 解析并清理字符串 URL；无效输入不进入遥测。
+func SanitizeRawURL(rawURL, routeTemplate string, queryPolicy QueryValuePolicy) string {
+	parsed, err := url.Parse(rawURL)
+	if err != nil {
+		return ""
+	}
+	sanitized := SanitizeURL(parsed, routeTemplate, queryPolicy)
+	return sanitized.String()
+}
+
+// SanitizeRequestTarget 返回仅包含安全路径和查询参数的请求目标。
+func SanitizeRequestTarget(source *url.URL, routeTemplate string, queryPolicy QueryValuePolicy) string {
+	if source == nil {
+		return ""
+	}
+	sanitized := SanitizeURL(source, routeTemplate, queryPolicy)
+	return sanitized.RequestURI()
+}
+
+// SanitizePath 在存在有效路由模板时使用模板，否则遮蔽已知携带凭据的路径段。
+func SanitizePath(rawPath, routeTemplate string) string {
+	if normalizedRoute := normalizeRouteTemplate(routeTemplate); normalizedRoute != "" {
+		return normalizedRoute
+	}
+	segments := strings.Split(rawPath, "/")
+	for index := 0; index+1 < len(segments); index++ {
+		if _, sensitive := sensitivePathParameterPredecessors[strings.ToLower(segments[index])]; sensitive {
+			segments[index+1] = redactedValue
+		}
+	}
+	return strings.Join(segments, "/")
+}
+
+// SanitizeQuery 按策略清理查询参数；空策略失效安全地移除全部参数。
+func SanitizeQuery(rawQuery string, policy QueryValuePolicy) string {
+	if policy == nil {
+		return ""
+	}
+	return policy(rawQuery)
+}
+
+// RemoveQueryValues 移除全部查询参数。
+func RemoveQueryValues(string) string {
+	return ""
+}
+
+// RedactSensitiveQueryValues 仅遮蔽敏感查询参数值。
+func RedactSensitiveQueryValues(rawQuery string) string {
+	return redactQueryValues(rawQuery, false)
+}
+
+// RedactAllQueryValues 遮蔽全部查询参数值并保留键名。
+func RedactAllQueryValues(rawQuery string) string {
+	return redactQueryValues(rawQuery, true)
+}
+
+func redactQueryValues(rawQuery string, redactAll bool) string {
+	if rawQuery == "" {
+		return ""
+	}
+	values, err := url.ParseQuery(rawQuery)
+	if err != nil {
+		return ""
+	}
+	for key := range values {
+		_, sensitive := sensitiveQueryKeys[strings.ToLower(key)]
+		if redactAll || sensitive {
+			values[key] = []string{redactedValue}
+		}
+	}
+	return values.Encode()
+}
+
+// RouteTemplateOrUnmatched 返回有效的注册路由模板，否则返回统一未匹配路径。
+func RouteTemplateOrUnmatched(routeTemplate string) string {
+	if normalized := normalizeRouteTemplate(routeTemplate); normalized != "" {
+		return normalized
+	}
+	return UnmatchedRoute
+}
+
+// IsSensitiveHeader 判断请求头是否包含凭据、签名或敏感身份信息。
+func IsSensitiveHeader(name string) bool {
+	_, sensitive := sensitiveHeaderNames[normalizeHeaderName(name)]
+	return sensitive
+}
+
+// RedactSensitiveHeaders 返回可安全写入日志或遥测的请求头副本。
+func RedactSensitiveHeaders(headers http.Header) map[string]string {
+	sanitized := make(map[string]string, len(headers))
+	for key, values := range headers {
+		if IsSensitiveHeader(key) {
+			sanitized[key] = redactedHeaderValue
+		} else if len(values) > 0 {
+			sanitized[key] = values[0]
+		}
+	}
+	return sanitized
+}
+
+func normalizeHeaderName(name string) string {
+	return strings.ToLower(strings.TrimSpace(name))
+}
+
+func normalizeRouteTemplate(routeTemplate string) string {
+	normalized := strings.TrimSpace(routeTemplate)
+	if !strings.HasPrefix(normalized, "/") || strings.ContainsAny(normalized, "?#\r\n") {
+		return ""
+	}
+	return normalized
+}

package/dist/resources/templates/go-backend/internal/common/requestprivacy/request_test.go

@@ -0,0 +1,170 @@
+package requestprivacy
+
+import (
+	"net/http"
+	"net/url"
+	"strings"
+	"testing"
+)
+
+func TestSanitizeURLUsesRouteTemplateAndClearsAlternateRepresentations(t *testing.T) {
+	requestURL := &url.URL{
+		Scheme:      "https",
+		Host:        "data.product-alpha.example",
+		User:        url.UserPassword("client", "secret"),
+		Opaque:      "//data.product-alpha.example/iap/google/orders/by-token/opaque-secret",
+		Path:        "/iap/google/orders/by-token/secret-purchase-token",
+		RawPath:     "/iap/google/orders/by-token/secret%2Fpurchase-token",
+		RawQuery:    "locale=en&token=secret-query-token",
+		Fragment:    "secret-fragment",
+		RawFragment: "secret-fragment",
+	}
+
+	got := SanitizeURL(requestURL, "/iap/google/orders/by-token/:purchaseToken", RedactSensitiveQueryValues)
+
+	if got.Path != "/iap/google/orders/by-token/:purchaseToken" || got.RawPath != "" {
+		t.Fatalf("path = %q, rawPath = %q", got.Path, got.RawPath)
+	}
+	if got.RawQuery != "locale=en&token=redacted" {
+		t.Fatalf("query = %q", got.RawQuery)
+	}
+	if got.User != nil || got.Opaque != "" || got.Fragment != "" || got.RawFragment != "" {
+		t.Fatalf("URL retained secret-bearing representations: %#v", got)
+	}
+	for _, secret := range []string{"secret", "purchase-token"} {
+		if strings.Contains(got.String(), secret) {
+			t.Fatalf("sanitized URL contains %q: %s", secret, got.String())
+		}
+	}
+}
+
+func TestSanitizePathRedactsSensitiveFallbackSegments(t *testing.T) {
+	tests := map[string]string{
+		"/api/v1/payment-results/result-secret":                                    "/api/v1/payment-results/redacted",
+		"/api/v1/users/me/notification-preferences/unsubscribe/unsubscribe-secret": "/api/v1/users/me/notification-preferences/unsubscribe/redacted",
+		"/api/v1/devices/device-capability":                                        "/api/v1/devices/redacted",
+		"/iap/google/orders/by-token/purchase-secret":                              "/iap/google/orders/by-token/redacted",
+	}
+	for rawPath, want := range tests {
+		t.Run(rawPath, func(t *testing.T) {
+			if got := SanitizePath(rawPath, ""); got != want {
+				t.Fatalf("SanitizePath() = %q, want %q", got, want)
+			}
+		})
+	}
+}
+
+func TestSanitizeQueryPolicies(t *testing.T) {
+	raw := "locale=en&q=refund+policy&state=secret"
+	if got := SanitizeQuery(raw, RedactSensitiveQueryValues); got != "locale=en&q=redacted&state=redacted" {
+		t.Fatalf("sensitive query = %q", got)
+	}
+	if got := SanitizeQuery(raw, RedactAllQueryValues); got != "locale=redacted&q=redacted&state=redacted" {
+		t.Fatalf("all query = %q", got)
+	}
+	if got := SanitizeQuery(raw, RemoveQueryValues); got != "" {
+		t.Fatalf("removed query = %q", got)
+	}
+	if got := SanitizeQuery(raw, nil); got != "" {
+		t.Fatalf("invalid-policy query = %q", got)
+	}
+}
+
+func TestRouteTemplateOrUnmatchedFailsClosed(t *testing.T) {
+	if got := RouteTemplateOrUnmatched("/api/v1/orders/:orderNo"); got != "/api/v1/orders/:orderNo" {
+		t.Fatalf("registered route = %q", got)
+	}
+	for _, route := range []string{"", "orders/:orderNo", "/orders/:orderNo?token=secret"} {
+		if got := RouteTemplateOrUnmatched(route); got != UnmatchedRoute {
+			t.Fatalf("route %q = %q", route, got)
+		}
+	}
+}
+
+func TestIsSensitiveHeaderCoversProductCapabilities(t *testing.T) {
+	for _, header := range []string{
+		"API-Key",
+		"Authorization",
+		"Baggage",
+		"Idempotency-Key",
+		"MCP-Session-Id",
+		"Stripe-Signature",
+		"Proxy-Authorization",
+		"X-Anonymous-Session-ID",
+		"X-Checkout-Session-Token",
+		"X-CSRF-Token",
+		"X-Goog-IAP-JWT-Assertion",
+		"X-Idempotency-Key",
+		"X-Onex-Delegated-Authority",
+		"X-Onex-Guest-Capability",
+		"X-OneX-Signature",
+		"X-OneX-Webhook-Signature",
+		"X-OSS-Signature",
+		"X-Preview-Token",
+		"X-Session-ID",
+		"X-Token-JTI",
+		"X-Hub-Signature-256",
+		"X-Signature",
+		"X-Webhook-Signature",
+		"X-Widget-App-Key",
+		"X-Widget-Session-UID",
+	} {
+		if !IsSensitiveHeader(header) {
+			t.Fatalf("header %s was not classified as sensitive", header)
+		}
+	}
+	if IsSensitiveHeader("X-Device-ID") {
+		t.Fatal("X-Device-ID unexpectedly classified as a credential")
+	}
+}
+
+func TestRedactSensitiveHeadersRemovesCredentialsAndIdentityValues(t *testing.T) {
+	headers := http.Header{
+		"API-Key":                  {"api-key-secret"},
+		"Authorization":            {"Bearer token-secret"},
+		"MCP-Session-Id":           {"mcp-session-secret"},
+		"X-Goog-IAP-JWT-Assertion": {"google-iap-assertion-secret"},
+		"X-Identity-ID":            {"identity-private-value"},
+		"X-OSS-Signature":          {"oss-signature-secret"},
+		"X-User-Public-ID":         {"user@example.com"},
+		"X-Device-ID":              {"device-public-value"},
+		"User-Agent":               {"privacy-test-agent", "ignored-second-value"},
+		"X-Webhook-Signature":      {"webhook-signature-secret"},
+	}
+
+	sanitized := RedactSensitiveHeaders(headers)
+
+	for _, key := range []string{
+		"API-Key",
+		"Authorization",
+		"MCP-Session-Id",
+		"X-Goog-IAP-JWT-Assertion",
+		"X-Identity-ID",
+		"X-OSS-Signature",
+		"X-User-Public-ID",
+		"X-Webhook-Signature",
+	} {
+		if sanitized[key] != "[REDACTED]" {
+			t.Fatalf("header %s = %q", key, sanitized[key])
+		}
+	}
+	if sanitized["X-Device-ID"] != "device-public-value" || sanitized["User-Agent"] != "privacy-test-agent" {
+		t.Fatalf("safe headers = %#v", sanitized)
+	}
+	for _, secret := range []string{
+		"api-key-secret",
+		"token-secret",
+		"mcp-session-secret",
+		"google-iap-assertion-secret",
+		"identity-private-value",
+		"oss-signature-secret",
+		"user@example.com",
+		"webhook-signature-secret",
+	} {
+		for _, value := range sanitized {
+			if strings.Contains(value, secret) {
+				t.Fatalf("sanitized headers retained %q: %#v", secret, sanitized)
+			}
+		}
+	}
+}

package/dist/resources/templates/go-backend/internal/common/response/pagination.go

@@ -0,0 +1,60 @@
+package response
+
+// PaginationMeta 分页元数据
+type PaginationMeta struct {
+	// 当前页码
+	Page int `json:"page"`
+	// 每页条数
+	PageSize int `json:"page_size"`
+	// 总记录数
+	Total int64 `json:"total"`
+	// 总页数
+	TotalPages int `json:"total_pages"`
+}
+
+// Paginated 分页响应泛型结构体
+type Paginated[T any] struct {
+	// 数据列表
+	Data []T `json:"data"`
+	// 分页信息
+	Pagination PaginationMeta `json:"pagination"`
+}
+
+// NewList 创建无分页的列表响应，保持与分页接口相同的 { data, pagination } 契约
+func NewList[T any](data []T) Paginated[T] {
+	if data == nil {
+		data = make([]T, 0)
+	}
+	count := len(data)
+	return Paginated[T]{
+		Data: data,
+		Pagination: PaginationMeta{
+			Page:       1,
+			PageSize:   count,
+			Total:      int64(count),
+			TotalPages: 1,
+		},
+	}
+}
+
+// NewPaginated 创建分页响应
+func NewPaginated[T any](data []T, page, pageSize int, total int64) Paginated[T] {
+	totalPages := 0
+	if pageSize > 0 {
+		totalPages = int((total + int64(pageSize) - 1) / int64(pageSize))
+	}
+
+	if data == nil {
+		data = make([]T, 0)
+	}
+
+	return Paginated[T]{
+		Data: data,
+		Pagination: PaginationMeta{
+			Page:       page,
+			PageSize:   pageSize,
+			Total:      total,
+			TotalPages: totalPages,
+		},
+	}
+}

package/dist/resources/templates/go-backend/internal/common/response/response.go

@@ -0,0 +1,110 @@
+package response
+
+import (
+	"errors"
+	"net/http"
+
+	"github.com/gin-gonic/gin"
+	"github.com/go-playground/validator/v10"
+
+	"{{module}}/internal/common/types"
+	"{{module}}/pkg/apierror"
+)
+
+// OK 200 成功响应
+func OK(c *gin.Context, data any) {
+	c.JSON(http.StatusOK, data)
+}
+
+// Created 201 创建成功响应
+func Created(c *gin.Context, data any) {
+	c.JSON(http.StatusCreated, data)
+}
+
+// Accepted 202 异步任务已接受响应
+func Accepted(c *gin.Context, data any) {
+	c.JSON(http.StatusAccepted, data)
+}
+
+// NoContent 204 无内容响应
+func NoContent(c *gin.Context) {
+	c.Status(http.StatusNoContent)
+}
+
+// Error 根据 error 类型自动选择状态码和响应格式
+func Error(c *gin.Context, err error) {
+	var httpErr apierror.HTTPError
+	if errors.As(err, &httpErr) {
+		status := httpErr.HTTPStatus()
+		// 410 Gone 响应附加 noindex 头，通知搜索引擎不再索引
+		if status == http.StatusGone {
+			c.Header("X-Robots-Tag", "noindex, nofollow")
+		}
+		if status == http.StatusTooManyRequests || status == http.StatusServiceUnavailable {
+			if retryAfter := httpErr.HTTPResponseMetadata().RetryAfter(); retryAfter != "" {
+				c.Header(types.HeaderRetryAfter, retryAfter)
+			}
+		}
+		c.JSON(status, httpErr.ToResponse())
+		return
+	}
+
+	// 未知错误：注入 Gin context 供 logging middleware 输出错误详情，返回通用 500
+	_ = c.Error(err)
+	internal := apierror.Internal("Internal server error")
+	c.JSON(internal.Status, internal.ToResponse())
+}
+
+// ValidationError 格式化 go-playground/validator 的校验错误
+func ValidationError(c *gin.Context, err error) {
+	var ve validator.ValidationErrors
+	if !errors.As(err, &ve) {
+		// 非 validator 校验错误，按普通错误处理
+		apiErr := apierror.BadRequest(apierror.CodeValidationFailed, err.Error())
+		c.JSON(apiErr.Status, apiErr.ToResponse())
+		return
+	}
+
+	fieldErrors := make([]apierror.FieldError, 0, len(ve))
+	for _, fe := range ve {
+		fieldErrors = append(fieldErrors, apierror.FieldError{
+			Field:   fe.Field(),
+			Message: formatValidationMessage(fe),
+		})
+	}
+
+	apiErr := apierror.ValidationFailed(fieldErrors)
+	c.JSON(apiErr.Status, apiErr.ToResponse())
+}
+
+// formatValidationMessage 将 validator tag 转换为可读的错误消息
+func formatValidationMessage(fe validator.FieldError) string {
+	switch fe.Tag() {
+	case "required":
+		return "is required"
+	case "email":
+		return "must be a valid email"
+	case "min":
+		return "must be at least " + fe.Param()
+	case "max":
+		return "must be at most " + fe.Param()
+	case "len":
+		return "must have length " + fe.Param()
+	case "oneof":
+		return "must be one of: " + fe.Param()
+	case "uuid":
+		return "must be a valid UUID"
+	case "url":
+		return "must be a valid URL"
+	case "gte":
+		return "must be greater than or equal to " + fe.Param()
+	case "lte":
+		return "must be less than or equal to " + fe.Param()
+	case "gt":
+		return "must be greater than " + fe.Param()
+	case "lt":
+		return "must be less than " + fe.Param()
+	default:
+		return "failed on " + fe.Tag() + " validation"
+	}
+}