@stackonward/cli 0.0.1 → 1.0.1

package/dist/resources/templates/go-backend/internal/core/audit/middleware.go

@@ -0,0 +1,669 @@
+package audit
+
+import (
+	"errors"
+	"math"
+	"net/http"
+	"strings"
+	"time"
+
+	"github.com/gin-gonic/gin"
+	"go.opentelemetry.io/otel/trace"
+	"go.uber.org/zap"
+	"gorm.io/datatypes"
+
+	commonmw "{{module}}/internal/common/middleware"
+	"{{module}}/internal/common/requestprivacy"
+	"{{module}}/internal/common/response"
+	"{{module}}/pkg/apierror"
+)
+
+// AuditMiddleware 审计中间件
+type AuditMiddleware struct {
+	svc             AuditService
+	operationPolicy OperationLogPolicy
+	logger          *zap.Logger
+}
+
+const operationPanicErrorMessage = "panic recovered"
+
+// NewAuditMiddleware 构建审计中间件
+func NewAuditMiddleware(svc AuditService, logger *zap.Logger) *AuditMiddleware {
+	return &AuditMiddleware{
+		svc:             svc,
+		operationPolicy: NewOperationLogPolicy(),
+		logger:          logger.Named("AuditMiddleware"),
+	}
+}
+
+// OperationLogPolicy 控制哪些请求需要完整操作日志。
+type OperationLogPolicy struct{}
+
+// NewOperationLogPolicy 构建操作日志策略。
+func NewOperationLogPolicy() OperationLogPolicy {
+	return OperationLogPolicy{}
+}
+
+// ShouldRecord 判断请求是否属于管理控制面操作。
+func (OperationLogPolicy) ShouldRecord(c *gin.Context) bool {
+	if c.Request.Method == "OPTIONS" {
+		return false
+	}
+	if strings.EqualFold(c.GetHeader("Upgrade"), "websocket") {
+		return false
+	}
+	path := operationRoutePath(c)
+	if isAuditExcludedPath(path) {
+		return false
+	}
+	return strings.HasPrefix(path, "/admin/") || strings.HasPrefix(path, "/api/v1/admin/")
+}
+
+// Handle 返回 Gin 中间件函数
+// 所有非跳过请求写入 sys_access_logs；当 Service 层注入了 Enrich 数据时，额外写入 sys_audit_logs
+func (m *AuditMiddleware) Handle() gin.HandlerFunc {
+	return func(c *gin.Context) {
+		if m.shouldSkip(c) {
+			c.Next()
+			return
+		}
+
+		startTime := time.Now()
+
+		// 注入审计增强容器，供 Service 层写入变更详情。
+		// EventMetadata 的 context 注入由全局 commonmw.EventMetadataInjector() 中间件
+		// 负责（cmd/platform-api/app.go 链上已注册），audit 中间件不再重复注入以避免
+		// 双写 + 构建器重复。
+		ctx := NewEnrichmentContext(c.Request.Context())
+		c.Request = c.Request.WithContext(ctx)
+
+		accessEntry := AccessEntryFromContext(c)
+		var operationLogID int64
+		operationStarted := false
+		if m.operationPolicy.ShouldRecord(c) {
+			entry := BeginOperationEntryFromContext(c, accessEntry)
+			id, err := m.svc.BeginOperation(c.Request.Context(), entry)
+			if err != nil {
+				m.logger.Error("operation log begin failed",
+					zap.String("requestId", accessEntry.RequestID),
+					zap.String("path", accessEntry.HTTPPath),
+					zap.Error(err),
+				)
+				response.Error(c, apierror.Internal("Operation audit failed"))
+				c.Abort()
+				return
+			}
+			operationLogID = id
+			operationStarted = true
+		}
+
+		defer func() {
+			panicValue := recover()
+			m.finalizeAuditRequest(c, startTime, accessEntry, operationStarted, operationLogID, panicValue)
+			if panicValue != nil {
+				panic(panicValue)
+			}
+		}()
+
+		// 执行业务处理器（响应在此步骤写入）
+		c.Next()
+	}
+}
+
+func (m *AuditMiddleware) finalizeAuditRequest(
+	c *gin.Context,
+	startTime time.Time,
+	accessEntry AccessEntry,
+	operationStarted bool,
+	operationLogID int64,
+	panicValue any,
+) {
+	rawDurationMS := time.Since(startTime).Milliseconds()
+	if rawDurationMS > math.MaxInt32 {
+		rawDurationMS = math.MaxInt32
+	}
+	durationMS := int32(rawDurationMS) //nolint:gosec // G115: 已显式边界检查
+	status := c.Writer.Status()
+	if panicValue != nil && status < http.StatusInternalServerError {
+		status = http.StatusInternalServerError
+	}
+	statusCode := int16(status) //nolint:gosec // G115: HTTP 状态码范围 100-599，不会溢出 int16
+
+	applyResourceDecisionPrincipal(c, &accessEntry)
+	accessEntry.HTTPStatus = statusCode
+	accessEntry.DurationMS = durationMS
+	accessEntry.IsSuccess = statusCode < http.StatusBadRequest
+	accessEntry.ErrorMessage = operationErrorMessage(c, panicValue, status)
+
+	m.svc.LogAccess(c.Request.Context(), accessEntry)
+
+	if operationStarted {
+		completeEntry := CompleteOperationEntryFromContext(c, accessEntry, statusCode, durationMS)
+		if err := m.svc.CompleteOperation(c.Request.Context(), operationLogID, completeEntry); err != nil {
+			m.logger.Error("operation log remained started",
+				zap.Int64("operationLogId", operationLogID),
+				zap.String("requestId", accessEntry.RequestID),
+				zap.Error(err),
+			)
+		}
+	}
+
+	m.writeEnrichedAuditEntries(c, accessEntry)
+}
+
+func applyResourceDecisionPrincipal(c *gin.Context, accessEntry *AccessEntry) {
+	if decision, ok := commonmw.GetResourcePermissionDecision(c); ok && decision.PrincipalID > 0 {
+		accessEntry.IAMPrincipalID = decision.PrincipalID
+	}
+}
+
+func operationErrorMessage(c *gin.Context, panicValue any, status int) string {
+	if panicValue != nil {
+		return operationPanicErrorMessage
+	}
+	if status < http.StatusBadRequest || len(c.Errors) == 0 {
+		return ""
+	}
+	return operationErrorEvidenceFromContext(c, status).Code
+}
+
+func (m *AuditMiddleware) writeEnrichedAuditEntries(c *gin.Context, accessEntry AccessEntry) {
+	enrichment := getEnrichment(c.Request.Context())
+	if enrichment == nil {
+		return
+	}
+	if enrichment.Changes == nil && enrichment.Metadata == nil && len(enrichment.AdditionalEntries) == 0 {
+		return
+	}
+	rule := matchRouteRule(c.Request.Method, operationRoutePath(c))
+	baseAuditEntry := AuditEntry{
+		TraceID:            accessEntry.TraceID,
+		RequestID:          accessEntry.RequestID,
+		ActorType:          accessEntry.ActorType,
+		ActorID:            accessEntry.ActorID,
+		AuthSubjectType:    accessEntry.AuthSubjectType,
+		IAMPrincipalID:     accessEntry.IAMPrincipalID,
+		CredentialPublicID: accessEntry.CredentialPublicID,
+		TokenFingerprint:   accessEntry.TokenFingerprint,
+		AuthMechanism:      accessEntry.AuthMechanism,
+		ActorIP:            accessEntry.ActorIP,
+		ActorUserAgent:     c.Request.UserAgent(),
+		TenantID:           commonmw.GetTenantID(c),
+		IsSuccess:          accessEntry.IsSuccess,
+		ErrorMessage:       accessEntry.ErrorMessage,
+	}
+	if enrichment.Changes != nil || enrichment.Metadata != nil {
+		resourceType, resourceID, productCode := applyAuditResourceOverride(
+			accessEntry.ResourceType,
+			accessEntry.ResourceID,
+			accessEntry.ProductCode,
+			enrichment.ResourceOverride,
+		)
+		auditEntry := baseAuditEntry
+		auditEntry.Action = rule.Action
+		auditEntry.Category = rule.Category
+		auditEntry.RiskLevel = rule.RiskLevel
+		auditEntry.ResourceType = resourceType
+		auditEntry.ResourceID = resourceID
+		auditEntry.ProductCode = productCode
+		auditEntry.Changes = enrichment.Changes
+		auditEntry.Metadata = enrichment.Metadata
+		m.svc.LogAudit(c.Request.Context(), auditEntry)
+	}
+	for _, additional := range enrichment.AdditionalEntries {
+		resourceType, resourceID, productCode := applyAuditResourceOverride(
+			accessEntry.ResourceType,
+			accessEntry.ResourceID,
+			accessEntry.ProductCode,
+			&additional.ResourceOverride,
+		)
+		auditEntry := baseAuditEntry
+		auditEntry.Action = additional.Action
+		auditEntry.Category = additional.Category
+		auditEntry.RiskLevel = additional.RiskLevel
+		auditEntry.ResourceType = resourceType
+		auditEntry.ResourceID = resourceID
+		auditEntry.ProductCode = productCode
+		auditEntry.Changes = additional.Changes
+		auditEntry.Metadata = additional.Metadata
+		m.svc.LogAudit(c.Request.Context(), auditEntry)
+	}
+}
+
+func applyAuditResourceOverride(resourceType, resourceID, productCode string, override *ResourceOverride) (string, string, string) {
+	if override == nil {
+		return resourceType, resourceID, productCode
+	}
+	if overrideResourceType := strings.TrimSpace(override.ResourceType); overrideResourceType != "" {
+		resourceType = overrideResourceType
+	}
+	if overrideResourceID := strings.TrimSpace(override.ResourceID); overrideResourceID != "" {
+		resourceID = overrideResourceID
+	}
+	if overrideProductCode := strings.TrimSpace(override.ProductCode); overrideProductCode != "" {
+		productCode = overrideProductCode
+	}
+	return resourceType, resourceID, productCode
+}
+
+// shouldSkip 判断是否应跳过审计
+func (m *AuditMiddleware) shouldSkip(c *gin.Context) bool {
+	for _, method := range skipMethods {
+		if c.Request.Method == method {
+			return true
+		}
+	}
+	return isAuditExcludedPath(c.Request.URL.Path)
+}
+
+// AccessEntryFromContext 从 gin.Context 提取访问日志字段
+func AccessEntryFromContext(c *gin.Context) AccessEntry {
+	routePath := operationRoutePath(c)
+	entry := AccessEntry{
+		RequestID:  commonmw.GetRequestID(c),
+		HTTPMethod: c.Request.Method,
+		HTTPPath:   routePath,
+		IsSuccess:  true,
+	}
+
+	// 提取产品上下文
+	if pc := commonmw.GetProductCode(c); pc != "" {
+		entry.ProductCode = string(pc)
+	}
+
+	// 提取操作者信息（actor = 业务用户 ID；audit 入口默认使用 user_id 与下游业务对账）
+	if iamPrincipal := commonmw.GetAuthenticatedIAMPrincipal(c); iamPrincipal != nil {
+		entry.ActorType = ActorTypeAPIKey
+		entry.ActorIP = iamPrincipal.SourceIP
+		entry.ActorUserAgent = c.Request.UserAgent()
+		entry.AuthSubjectType = iamPrincipal.AuthSubjectType
+		entry.IAMPrincipalID = iamPrincipal.PrincipalID
+		entry.CredentialPublicID = iamPrincipal.CredentialPublicID
+		entry.TokenFingerprint = iamPrincipal.TokenFingerprint
+		entry.AuthMechanism = iamPrincipal.AuthMechanism
+	} else if identity := commonmw.GetUserIdentity(c); identity != nil {
+		entry.ActorID = identity.UserID
+		entry.AuthSubjectType = "user"
+		entry.AuthMechanism = "gateway_jwt"
+		switch identity.Type {
+		case "admin", "super_admin":
+			entry.ActorType = ActorTypeAdmin
+		default:
+			entry.ActorType = ActorTypeUser
+		}
+	} else {
+		entry.ActorType = ActorTypeSystem
+	}
+
+	// 提取客户端上下文
+	if cc := commonmw.GetClientContext(c); cc != nil {
+		if entry.ActorIP == "" {
+			entry.ActorIP = cc.IP
+		}
+		entry.ActorUserAgent = c.Request.UserAgent()
+	}
+
+	entry.ResourceType = extractResourceType(routePath)
+	entry.ResourceID = extractResourceID(c)
+
+	// 从 OTel span context 提取 trace_id
+	if span := trace.SpanFromContext(c.Request.Context()); span.SpanContext().IsValid() {
+		entry.TraceID = span.SpanContext().TraceID().String()
+	}
+
+	return entry
+}
+
+// routeRule 路由审计规则
+type routeRule struct {
+	Action    AuditAction
+	Category  AuditCategory
+	RiskLevel RiskLevel
+}
+
+// matchRouteRule 匹配路由规则（按优先级从高到低）
+func matchRouteRule(method, path string) routeRule {
+	path = normalizeAuditRoutePath(path)
+	switch {
+	case method == "DELETE" && strings.HasPrefix(path, "/admin/"):
+		return routeRule{ActionDelete, inferCategory(path), RiskLevelCritical}
+	case method == "POST" && strings.Contains(path, "/refund"):
+		return routeRule{ActionRefund, CategoryCommerce, RiskLevelCritical}
+	case method == "POST" && strings.Contains(path, "/export"):
+		return routeRule{ActionExport, inferCategory(path), RiskLevelCritical}
+	case method == "POST" && strings.Contains(path, "/suspend"):
+		return routeRule{ActionSuspend, CategoryIdentity, RiskLevelCritical}
+	case method == "DELETE" && strings.Contains(path, "/subscriptions/"):
+		return routeRule{ActionCancel, CategoryCommerce, RiskLevelCritical}
+	case method == "POST" && strings.Contains(path, "/auth/login"):
+		return routeRule{ActionLogin, CategoryAuth, RiskLevelHigh}
+	case method == "POST" && strings.Contains(path, "/auth/logout"):
+		return routeRule{ActionLogout, CategoryAuth, RiskLevelHigh}
+	case method == "POST" && strings.Contains(path, "/auth/register"):
+		return routeRule{ActionRegister, CategoryAuth, RiskLevelHigh}
+	case method == "POST" && strings.Contains(path, "/password"):
+		return routeRule{ActionPasswordChange, CategoryAuth, RiskLevelHigh}
+	case method == "POST" && strings.Contains(path, "/mfa"):
+		return routeRule{ActionMFAEnable, CategoryAuth, RiskLevelHigh}
+	case method == "DELETE" && strings.Contains(path, "/mfa"):
+		return routeRule{ActionMFADisable, CategoryAuth, RiskLevelHigh}
+	case method == "POST" && strings.HasPrefix(path, "/admin/identity/sso/connections/") && strings.HasSuffix(path, "/test"):
+		return routeRule{ActionExecute, CategoryIdentity, RiskLevelHigh}
+	case method == "POST" && strings.HasPrefix(path, "/admin/identity/sso/connections/") && strings.HasSuffix(path, "/enable"):
+		return routeRule{ActionActivate, CategoryIdentity, RiskLevelCritical}
+	case method == "POST" && strings.HasPrefix(path, "/admin/identity/sso/connections/") && strings.HasSuffix(path, "/disable"):
+		return routeRule{ActionSuspend, CategoryIdentity, RiskLevelCritical}
+	case method == "POST" && strings.HasPrefix(path, "/admin/identity/sso/connections/") && strings.Contains(path, "/provisioning-tokens/") && strings.HasSuffix(path, "/revoke"):
+		return routeRule{ActionDelete, CategoryIdentity, RiskLevelCritical}
+	case method == "POST" && strings.HasPrefix(path, "/admin/identity/sso/connections/") && strings.Contains(path, "/provisioning-token"):
+		return routeRule{ActionGenerate, CategoryIdentity, RiskLevelCritical}
+	case method == "POST" && strings.HasPrefix(path, "/admin/identity/sso/connections/") && strings.HasSuffix(path, "/challenge"):
+		return routeRule{ActionGenerate, CategoryIdentity, RiskLevelHigh}
+	case method == "POST" && strings.HasPrefix(path, "/admin/identity/sso/connections/") && strings.HasSuffix(path, "/verify"):
+		return routeRule{ActionVerify, CategoryIdentity, RiskLevelHigh}
+	case method == "POST" && strings.HasPrefix(path, "/admin/delivery/capacity/templates/") && strings.HasSuffix(path, "/publish"):
+		return routeRule{ActionPublish, CategoryCommerce, RiskLevelHigh}
+	case method == "POST" && strings.HasPrefix(path, "/admin/delivery/capacity/templates/") && strings.HasSuffix(path, "/archive"):
+		return routeRule{ActionArchive, CategoryCommerce, RiskLevelHigh}
+	case method == "POST" && strings.HasPrefix(path, "/admin/delivery/capacity/templates/") && strings.HasSuffix(path, "/validate"):
+		return routeRule{ActionVerify, CategoryCommerce, RiskLevelMedium}
+	case method == "POST" && strings.HasPrefix(path, "/admin/delivery/capacity/templates/") && strings.HasSuffix(path, "/generation-preview"):
+		return routeRule{ActionGenerate, CategoryCommerce, RiskLevelMedium}
+	case method == "POST" && strings.HasPrefix(path, "/admin/delivery/capacity/templates/") && strings.HasSuffix(path, "/generate"):
+		return routeRule{ActionGenerate, CategoryCommerce, RiskLevelHigh}
+	case method == "POST" && strings.Contains(path, "/orders"):
+		return routeRule{ActionCreate, CategoryCommerce, RiskLevelHigh}
+	case method == "PUT" && strings.HasPrefix(path, "/admin/iam/service-accounts/") && strings.HasSuffix(path, "/trust-policy"):
+		return routeRule{ActionUpdate, CategorySystem, RiskLevelHigh}
+	case method == "POST" && strings.HasPrefix(path, "/admin/"):
+		return routeRule{ActionCreate, inferCategory(path), RiskLevelHigh}
+	case method == "PUT" && strings.HasPrefix(path, "/admin/"):
+		return routeRule{ActionUpdate, inferCategory(path), RiskLevelMedium}
+	case method == "PATCH" && strings.HasPrefix(path, "/admin/"):
+		return routeRule{ActionUpdate, inferCategory(path), RiskLevelMedium}
+	case (method == "PUT" || method == "PATCH") && strings.Contains(path, "/users/"):
+		return routeRule{ActionUpdate, CategoryUser, RiskLevelMedium}
+	case method == "DELETE" && strings.Contains(path, "/addresses/"):
+		return routeRule{ActionDelete, CategoryUser, RiskLevelHigh}
+	case method == "DELETE":
+		return routeRule{ActionDelete, inferCategory(path), RiskLevelHigh}
+	case method == "POST":
+		return routeRule{ActionCreate, inferCategory(path), RiskLevelMedium}
+	case method == "PUT" || method == "PATCH":
+		return routeRule{ActionUpdate, inferCategory(path), RiskLevelMedium}
+	default:
+		return routeRule{ActionRead, inferCategory(path), RiskLevelLow}
+	}
+}
+
+func normalizeAuditRoutePath(path string) string {
+	for _, prefix := range []string{"/api/v1", "/api/v2"} {
+		if strings.HasPrefix(path, prefix+"/admin/") {
+			return strings.TrimPrefix(path, prefix)
+		}
+	}
+	return path
+}
+
+// inferCategory 从路径推断业务分类
+func inferCategory(path string) AuditCategory {
+	switch {
+	case strings.Contains(path, "/auth/"):
+		return CategoryAuth
+	case strings.Contains(path, "/identities/") || strings.Contains(path, "/identity/"):
+		return CategoryIdentity
+	case strings.Contains(path, "/users/"):
+		return CategoryUser
+	case strings.Contains(path, "/orders/") || strings.Contains(path, "/payments/") ||
+		strings.Contains(path, "/subscriptions/") || strings.Contains(path, "/invoices/"):
+		return CategoryCommerce
+	case strings.Contains(path, "/catalog/") || strings.Contains(path, "/pricing/") ||
+		strings.Contains(path, "/config/"):
+		return CategoryConfig
+	case strings.Contains(path, "/notifications/") || strings.Contains(path, "/templates/"):
+		return CategoryContent
+	case strings.Contains(path, "/files/") || strings.Contains(path, "/storage/"):
+		return CategoryStorage
+	default:
+		return CategorySystem
+	}
+}
+
+// extractResourceType 从路径提取资源类型
+func extractResourceType(path string) string {
+	segments := strings.Split(strings.Trim(path, "/"), "/")
+	skip := map[string]bool{"api": true, "v1": true, "v2": true, "admin": true, "internal": true}
+	for _, seg := range segments {
+		if seg == "" || skip[seg] {
+			continue
+		}
+		if strings.HasPrefix(seg, ":") {
+			continue
+		}
+		return seg
+	}
+	return ""
+}
+
+// extractResourceID 从路由参数提取资源 ID
+func extractResourceID(c *gin.Context) string {
+	for _, paramName := range []string{"id", "userId", "identityId", "orderId", "subscriptionId", "taskId"} {
+		if id := c.Param(paramName); id != "" {
+			return strings.TrimPrefix(id, "/")
+		}
+	}
+	return ""
+}
+
+// BeginOperationEntryFromContext 从请求上下文构建操作开始记录。
+func BeginOperationEntryFromContext(c *gin.Context, accessEntry AccessEntry) BeginOperationEntry {
+	rule := matchRouteRule(c.Request.Method, operationRoutePath(c))
+	sourceModule := extractOperationSourceModule(operationRoutePath(c))
+	return BeginOperationEntry{
+		TraceID:            accessEntry.TraceID,
+		RequestID:          accessEntry.RequestID,
+		ActorType:          accessEntry.ActorType,
+		ActorID:            accessEntry.ActorID,
+		AuthSubjectType:    accessEntry.AuthSubjectType,
+		IAMPrincipalID:     accessEntry.IAMPrincipalID,
+		CredentialPublicID: accessEntry.CredentialPublicID,
+		TokenFingerprint:   accessEntry.TokenFingerprint,
+		AuthMechanism:      accessEntry.AuthMechanism,
+		ActorIP:            accessEntry.ActorIP,
+		ActorUserAgent:     accessEntry.ActorUserAgent,
+		OperationAction:    rule.Action,
+		OperationCategory:  rule.Category,
+		RiskLevel:          rule.RiskLevel,
+		SourceModule:       sourceModule,
+		HTTPMethod:         accessEntry.HTTPMethod,
+		HTTPPath:           accessEntry.HTTPPath,
+		ProductCode:        accessEntry.ProductCode,
+		TenantID:           commonmw.GetTenantID(c),
+		ResourceType:       accessEntry.ResourceType,
+		ResourceID:         accessEntry.ResourceID,
+		RequestContext: BuildOperationRequestContext(OperationRequestEnvelopeInput{
+			RouteTemplate:   operationRoutePath(c),
+			QueryKeyNames:   operationQueryKeyNames(c),
+			RouteParamNames: operationRouteParamNames(c),
+			ContentType:     c.GetHeader("Content-Type"),
+			ProductCode:     accessEntry.ProductCode,
+			TenantID:        commonmw.GetTenantID(c),
+		}),
+		OperationMetadata: BuildOperationMetadata(OperationMetadataEnvelopeInput{
+			SourceModule: sourceModule,
+			RouteName:    operationRoutePath(c),
+			Handler:      c.HandlerName(),
+			ResourceHint: operationResourceHint(accessEntry.ResourceType, accessEntry.ResourceID),
+		}),
+	}
+}
+
+// CompleteOperationEntryFromContext 从响应上下文构建操作完成记录。
+func CompleteOperationEntryFromContext(c *gin.Context, accessEntry AccessEntry, status int16, durationMS int32) CompleteOperationEntry {
+	entry := CompleteOperationEntry{
+		RequestID:       accessEntry.RequestID,
+		IAMPrincipalID:  accessEntry.IAMPrincipalID,
+		HTTPStatus:      status,
+		DurationMS:      durationMS,
+		IsSuccess:       status < http.StatusBadRequest,
+		ErrorMessage:    accessEntry.ErrorMessage,
+		ResponseContext: BuildOperationResponseContext(operationResponseInput(c, int(status))),
+		PolicyViolation: datatypesJSONEmpty(),
+	}
+	if decision, ok := commonmw.GetResourcePermissionDecision(c); ok {
+		if decision.PrincipalID > 0 {
+			entry.IAMPrincipalID = decision.PrincipalID
+		}
+		entry.IAMAction = decision.Action
+		entry.IAMResource = decision.Resource
+		entry.DecisionAllowed = decision.Allowed
+		entry.DecisionReasonCode = decision.ReasonCode
+		entry.DecisionReasonKind = string(decision.ReasonKind)
+		if entry.ErrorMessage == "" && !decision.Allowed {
+			entry.ErrorMessage = decision.ReasonCode
+		}
+		entry.PolicyViolation = BuildOperationPolicyViolation(OperationPolicyEnvelopeInput{
+			IAMAction:              decision.Action,
+			IAMResource:            decision.Resource,
+			Allowed:                decision.Allowed,
+			ReasonCode:             decision.ReasonCode,
+			ReasonKind:             string(decision.ReasonKind),
+			ScopeConstraintSummary: decision.ScopeConstraintSummary,
+		})
+	}
+	return entry
+}
+
+func operationRoutePath(c *gin.Context) string {
+	routeTemplate := requestprivacy.RouteTemplateOrUnmatched(c.FullPath())
+	return requestprivacy.SanitizePath(c.Request.URL.Path, routeTemplate)
+}
+
+func operationQueryKeyNames(c *gin.Context) []string {
+	values := c.Request.URL.Query()
+	keys := make([]string, 0, len(values))
+	for key := range values {
+		keys = append(keys, key)
+	}
+	return keys
+}
+
+func operationRouteParamNames(c *gin.Context) []string {
+	if len(c.Params) == 0 {
+		return nil
+	}
+	params := make([]string, 0, len(c.Params))
+	for _, param := range c.Params {
+		params = append(params, param.Key)
+	}
+	return params
+}
+
+func operationResponseInput(c *gin.Context, status int) OperationResponseEnvelopeInput {
+	errorEvidence := operationErrorEvidenceFromContext(c, status)
+	return OperationResponseEnvelopeInput{
+		Status:            status,
+		ErrorCode:         errorEvidence.Code,
+		ErrorType:         errorEvidence.Type,
+		ErrorCount:        errorEvidence.Count,
+		ResponseSizeClass: responseSizeClass(c.Writer.Size()),
+	}
+}
+
+type operationErrorEvidence struct {
+	Code  string
+	Type  string
+	Count int
+}
+
+func operationErrorEvidenceFromContext(c *gin.Context, status int) operationErrorEvidence {
+	errorCode, errorType := operationErrorFields(status)
+	evidence := operationErrorEvidence{
+		Code:  errorCode,
+		Type:  errorType,
+		Count: len(c.Errors),
+	}
+	if evidence.Count == 0 {
+		return evidence
+	}
+	if evidence.Code == "" {
+		evidence.Code = apierror.CodeInternalError
+	}
+	evidence.Type = apierror.TypeAPI
+	for index := len(c.Errors) - 1; index >= 0; index-- {
+		var apiErr *apierror.APIError
+		if !errors.As(c.Errors[index].Err, &apiErr) || apiErr == nil {
+			continue
+		}
+		if code := strings.TrimSpace(apiErr.Detail.Code); code != "" {
+			evidence.Code = code
+		}
+		if errorType := strings.TrimSpace(apiErr.Detail.Type); errorType != "" {
+			evidence.Type = errorType
+		}
+		break
+	}
+	return evidence
+}
+
+func operationErrorFields(status int) (string, string) {
+	if status < 400 {
+		return "", ""
+	}
+	switch status {
+	case 400:
+		return apierror.CodeValidationFailed, apierror.ErrorTypeFromStatus(status)
+	case 401:
+		return apierror.CodeUnauthorized, apierror.ErrorTypeFromStatus(status)
+	case 403:
+		return apierror.CodeAccessDenied, apierror.ErrorTypeFromStatus(status)
+	case 404:
+		return apierror.CodeResourceNotFound, apierror.ErrorTypeFromStatus(status)
+	default:
+		return apierror.CodeInternalError, apierror.ErrorTypeFromStatus(status)
+	}
+}
+
+func responseSizeClass(size int) string {
+	switch {
+	case size < 0:
+		return ""
+	case size < 1024:
+		return "small"
+	case size < 64*1024:
+		return "medium"
+	default:
+		return "large"
+	}
+}
+
+func extractOperationSourceModule(path string) string {
+	segments := strings.Split(strings.Trim(path, "/"), "/")
+	for i, segment := range segments {
+		if segment != "admin" {
+			continue
+		}
+		if i+1 < len(segments) {
+			next := segments[i+1]
+			if next != "" && !strings.HasPrefix(next, ":") {
+				return next
+			}
+		}
+		return ""
+	}
+	return extractResourceType(path)
+}
+
+func operationResourceHint(resourceType, resourceID string) string {
+	if resourceType == "" {
+		return ""
+	}
+	if resourceID == "" {
+		return resourceType
+	}
+	return resourceType + ":" + resourceID
+}
+
+func datatypesJSONEmpty() datatypes.JSON {
+	return datatypes.JSON([]byte("{}"))
+}