@stackonward/cli 0.0.1 → 1.0.0

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

@@ -0,0 +1,319 @@
+package audit
+
+import (
+	"context"
+	"encoding/hex"
+	"fmt"
+	"strconv"
+	"strings"
+
+	"github.com/google/uuid"
+	"go.uber.org/zap"
+	"{{module}}/internal/common/types"
+	"{{module}}/internal/core/eventbus"
+	"{{module}}/internal/core/outbox"
+)
+
+// EventProjection 由事件所有者解释业务载荷，基础设施只处理审计信封与持久化。
+type EventProjection interface {
+	Project(eventbus.DomainEvent) (*AuditEntry, *LoginEntry, error)
+}
+
+// EventBinding 明确订阅范围及持久化保证，避免全局通配导致跨进程重复审计。
+type EventBinding struct {
+	Pattern    string
+	Projection EventProjection
+	Durable    bool
+	Reliable   bool
+}
+
+// ListenerConfig 在启动时声明全部审计订阅，不在运行时变更。
+type ListenerConfig struct{ Bindings []EventBinding }
+
+// AuditListener 将已声明事件投影到审计存储。
+type AuditListener struct {
+	svc      AuditService
+	logger   *zap.Logger
+	bindings []EventBinding
+}
+
+// NewAuditListener 校验启动订阅并冻结配置快照。
+func NewAuditListener(svc AuditService, logger *zap.Logger, cfg ListenerConfig) (*AuditListener, error) {
+	seen := make(map[string]struct{}, len(cfg.Bindings))
+	for _, binding := range cfg.Bindings {
+		if strings.TrimSpace(binding.Pattern) == "" || (binding.Pattern == "**" || binding.Pattern == "*") || binding.Projection == nil {
+			return nil, fmt.Errorf("audit event binding requires an explicit pattern and projection")
+		}
+		if _, exists := seen[binding.Pattern]; exists {
+			return nil, fmt.Errorf("duplicate audit event pattern %s", binding.Pattern)
+		}
+		seen[binding.Pattern] = struct{}{}
+	}
+	return &AuditListener{svc: svc, logger: logger.Named("AuditListener"), bindings: append([]EventBinding(nil), cfg.Bindings...)}, nil
+}
+
+// Register 仅订阅显式注册的事件范围。
+func (l *AuditListener) Register(bus *eventbus.EventBus) {
+	for _, binding := range l.bindings {
+		propagateErrors := false
+		bus.Subscribe(binding.Pattern, func(ctx context.Context, event eventbus.DomainEvent) error {
+			return l.handleEvent(ctx, event, binding)
+		}, eventbus.SubscribeOptions{Priority: -10, CatchErrors: &propagateErrors})
+	}
+}
+
+func (l *AuditListener) handleEvent(ctx context.Context, event eventbus.DomainEvent, binding EventBinding) error {
+	entry, login, err := binding.Projection.Project(event)
+	if err != nil {
+		return outbox.MarkPermanentDelivery(err)
+	}
+	if (binding.Durable || binding.Reliable) && login != nil {
+		return outbox.MarkPermanentDelivery(fmt.Errorf("durable audit event %s cannot use asynchronous login projection", event.EventName))
+	}
+	if entry == nil && login == nil {
+		return outbox.MarkPermanentDelivery(fmt.Errorf("audit mapping is missing for event %s", event.EventName))
+	}
+	if entry != nil {
+		if err := l.fillAuditCommonFields(entry, event); err != nil {
+			return outbox.MarkPermanentDelivery(err)
+		}
+		l.extractAuditChanges(entry, event)
+		if binding.Reliable {
+			if _, err := uuid.Parse(strings.TrimSpace(event.EventID)); err != nil {
+				return outbox.MarkPermanentDelivery(fmt.Errorf("audit source event id is invalid: %w", err))
+			}
+			if event.AuditMeta == nil || event.AuditMeta.Actor == nil {
+				return outbox.MarkPermanentDelivery(fmt.Errorf("audit actor snapshot is required for event %s", event.EventName))
+			}
+			if entry.Metadata == nil {
+				entry.Metadata = &MetadataPayload{}
+			}
+			extra := make(map[string]any, len(entry.Metadata.Extra)+1)
+			for key, value := range entry.Metadata.Extra {
+				extra[key] = value
+			}
+			extra["source_event_id"] = event.EventID
+			entry.Metadata.Extra = extra
+			if err := l.svc.ProjectEventSync(ctx, event.EventID, event.EventName, *entry); err != nil {
+				return err
+			}
+		} else if binding.Durable {
+			if entry.EventID == "" || entry.OccurredAt.IsZero() {
+				return outbox.MarkPermanentDelivery(fmt.Errorf("durable audit event %s has an incomplete event envelope", event.EventName))
+			}
+			if err := l.svc.LogSync(ctx, *entry); err != nil {
+				return fmt.Errorf("persist durable audit event %s: %w", event.EventName, err)
+			}
+		} else {
+			l.svc.LogAudit(ctx, *entry)
+		}
+	}
+	if login != nil {
+		l.fillLoginCommonFields(login, event)
+		l.svc.LogLogin(ctx, *login)
+	}
+	return nil
+}
+
+func (l *AuditListener) fillAuditCommonFields(entry *AuditEntry, event eventbus.DomainEvent) error {
+	entry.EventID = event.EventID
+	entry.OccurredAt = event.OccurredAt
+	if event.Metadata != nil {
+		// EventMetadata.UserID 仍为 int64（跨进程序列化稳定形态），在审计层转换为 types.UserID
+		entry.ActorID = types.UserID(event.Metadata.UserID)
+		entry.TraceID = event.Metadata.TraceID
+		entry.TenantID = event.Metadata.TenantID
+		// 从扩展元数据获取客户端信息
+		if entry.ActorIP == "" {
+			if ip, ok := event.Metadata.Extra["client_ip"].(string); ok {
+				entry.ActorIP = ip
+			}
+		}
+		if entry.ActorUserAgent == "" {
+			if ua, ok := event.Metadata.Extra["user_agent"].(string); ok {
+				entry.ActorUserAgent = ua
+			}
+		}
+		if entry.RequestID == "" {
+			if rid, ok := event.Metadata.Extra["request_id"].(string); ok {
+				entry.RequestID = rid
+			}
+		}
+		if entry.ProductCode == "" {
+			if pc, ok := event.Metadata.Extra["product_code"].(string); ok {
+				entry.ProductCode = pc
+			}
+		}
+	}
+	// 认证事件的 AggregateID 就是 identity_id，可安全回填 ActorID
+	// 其他事件的 AggregateID 是业务资源 ID（如 task_id），不能当 user_id 用
+	if entry.ActorID.IsZero() && event.AggregateID != "" && entry.Category == CategoryAuth {
+		if id, err := strconv.ParseInt(event.AggregateID, 10, 64); err == nil && id > 0 {
+			entry.ActorID = types.UserID(id)
+		}
+	}
+	if event.AuditMeta != nil {
+		if err := restoreAuditActorSnapshot(entry, event.AuditMeta.Actor); err != nil {
+			return err
+		}
+	}
+	if entry.ActorType == "" {
+		if entry.ActorID.Valid() {
+			entry.ActorType = ActorTypeUser
+		} else {
+			entry.ActorType = ActorTypeSystem
+		}
+	}
+	return nil
+}
+
+func restoreAuditActorSnapshot(entry *AuditEntry, snapshot *eventbus.AuditActorSnapshotPayload) error {
+	if entry == nil || snapshot == nil {
+		return nil
+	}
+	actorType, ok := auditActorType(snapshot.ActorType)
+	if !ok || snapshot.ActorID < 0 || snapshot.IAMPrincipalID < 0 {
+		return fmt.Errorf("audit actor snapshot identity is invalid")
+	}
+	authSubjectType := strings.TrimSpace(snapshot.AuthSubjectType)
+	credentialPublicID := strings.TrimSpace(snapshot.CredentialPublicID)
+	tokenFingerprint := strings.TrimSpace(snapshot.TokenFingerprint)
+	authMechanism := strings.TrimSpace(snapshot.AuthMechanism)
+	if tokenFingerprint != "" {
+		decoded, err := hex.DecodeString(tokenFingerprint)
+		if err != nil || len(decoded) != 32 {
+			return fmt.Errorf("audit actor snapshot token fingerprint is invalid")
+		}
+	}
+	switch actorType {
+	case ActorTypeAdmin:
+		if snapshot.ActorID <= 0 || snapshot.IAMPrincipalID <= 0 || authSubjectType != "user" || authMechanism == "" ||
+			credentialPublicID != "" || tokenFingerprint != "" {
+			return fmt.Errorf("audit admin actor snapshot is invalid")
+		}
+	case ActorTypeAPIKey:
+		if snapshot.ActorID != 0 || snapshot.IAMPrincipalID <= 0 || authSubjectType == "" ||
+			credentialPublicID == "" || tokenFingerprint == "" || authMechanism == "" {
+			return fmt.Errorf("audit api key actor snapshot is invalid")
+		}
+	case ActorTypeUser:
+		if snapshot.ActorID <= 0 {
+			return fmt.Errorf("audit user actor snapshot is invalid")
+		}
+	case ActorTypeSystem, ActorTypeWebhook:
+		if snapshot.ActorID != 0 {
+			return fmt.Errorf("audit non-user actor snapshot is invalid")
+		}
+	}
+	entry.ActorType = actorType
+	entry.ActorID = types.UserID(snapshot.ActorID)
+	entry.AuthSubjectType = authSubjectType
+	entry.IAMPrincipalID = snapshot.IAMPrincipalID
+	entry.CredentialPublicID = credentialPublicID
+	entry.TokenFingerprint = tokenFingerprint
+	entry.AuthMechanism = authMechanism
+	return nil
+}
+
+func auditActorType(value string) (ActorType, bool) {
+	actorType := ActorType(strings.TrimSpace(value))
+	switch actorType {
+	case ActorTypeUser, ActorTypeAdmin, ActorTypeSystem, ActorTypeAPIKey, ActorTypeWebhook:
+		return actorType, true
+	default:
+		return "", false
+	}
+}
+
+// fillLoginCommonFields 从事件元数据填充登录条目公共字段
+func (l *AuditListener) fillLoginCommonFields(entry *LoginEntry, event eventbus.DomainEvent) {
+	if event.Metadata != nil {
+		// 登录事件由 auth 域发布，event.Metadata.UserID 实际承载的是 identity_id
+		// （EventMetadata 跨进程序列化保留 int64，避免 schema 跨域分裂）。
+		if entry.IdentityID.IsZero() && event.Metadata.UserID > 0 {
+			entry.IdentityID = types.IdentityID(event.Metadata.UserID)
+		}
+		if entry.ActorIP == "" {
+			if ip, ok := event.Metadata.Extra["client_ip"].(string); ok {
+				entry.ActorIP = ip
+			}
+		}
+		if entry.ActorUserAgent == "" {
+			if ua, ok := event.Metadata.Extra["user_agent"].(string); ok {
+				entry.ActorUserAgent = ua
+			}
+		}
+		if entry.RequestID == "" {
+			if rid, ok := event.Metadata.Extra["request_id"].(string); ok {
+				entry.RequestID = rid
+			}
+		}
+		if entry.ProductCode == "" {
+			if pc, ok := event.Metadata.Extra["product_code"].(string); ok {
+				entry.ProductCode = pc
+			}
+		}
+		// 可选客户端维度只接受事件信封事实；缺失时保持空值，禁止从其他字段推断。
+		if entry.DeviceType == "" {
+			if v, ok := event.Metadata.Extra["device_type"].(string); ok {
+				entry.DeviceType = v
+			}
+		}
+		if entry.OSName == "" {
+			if v, ok := event.Metadata.Extra["os_name"].(string); ok {
+				entry.OSName = v
+			}
+		}
+		if entry.BrowserName == "" {
+			if v, ok := event.Metadata.Extra["browser_name"].(string); ok {
+				entry.BrowserName = v
+			}
+		}
+		if entry.GeoCountry == "" {
+			if v, ok := event.Metadata.Extra["geo_country"].(string); ok {
+				entry.GeoCountry = v
+			}
+		}
+		if entry.GeoCity == "" {
+			if v, ok := event.Metadata.Extra["geo_city"].(string); ok {
+				entry.GeoCity = v
+			}
+		}
+	}
+	// 认证事件（login/register）时 Metadata.UserID 为 0（用户尚未认证），
+	// 从 AggregateID（identity_id）回填 IdentityID
+	if entry.IdentityID.IsZero() && event.AggregateID != "" {
+		if id, err := strconv.ParseInt(event.AggregateID, 10, 64); err == nil && id > 0 {
+			entry.IdentityID = types.IdentityID(id)
+		}
+	}
+	if entry.ActorType == "" {
+		if entry.IdentityID.Valid() {
+			entry.ActorType = ActorTypeUser
+		} else {
+			entry.ActorType = ActorTypeSystem
+		}
+	}
+}
+
+// extractAuditChanges 从事件信封提取审计变更快照
+//
+// 审计数据在 DomainEvent 的信封层字段（AuditChanges / AuditMeta），
+// 与业务 Payload 完全分离。遵循 AWS CloudTrail 模式：
+// 事件信封携带审计元数据，payload 只包含业务数据。
+func (l *AuditListener) extractAuditChanges(entry *AuditEntry, event eventbus.DomainEvent) {
+	if event.AuditChanges != nil {
+		entry.Changes = &ChangesPayload{
+			Before: event.AuditChanges.Before,
+			After:  event.AuditChanges.After,
+		}
+	}
+	if event.AuditMeta != nil {
+		entry.Metadata = &MetadataPayload{
+			Reason:              event.AuditMeta.Reason,
+			RelatedResourceID:   event.AuditMeta.RelatedResourceID,
+			RelatedResourceType: event.AuditMeta.RelatedResourceType,
+			Extra:               event.AuditMeta.Extra,
+		}
+	}
+}

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

@@ -0,0 +1,98 @@
+package audit
+
+import (
+	"context"
+	"errors"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/require"
+	"go.uber.org/zap"
+	"{{module}}/internal/core/eventbus"
+)
+
+type projectionFunc func(eventbus.DomainEvent) (*AuditEntry, *LoginEntry, error)
+
+func (f projectionFunc) Project(event eventbus.DomainEvent) (*AuditEntry, *LoginEntry, error) {
+	return f(event)
+}
+
+type projectionAuditService struct {
+	AuditService
+	entries  []AuditEntry
+	reliable int
+	async    int
+	failure  error
+}
+
+func (s *projectionAuditService) LogSync(_ context.Context, entry AuditEntry) error {
+	if s.failure != nil {
+		return s.failure
+	}
+	s.entries = append(s.entries, entry)
+	return nil
+}
+func (s *projectionAuditService) ProjectEventSync(ctx context.Context, _, _ string, entry AuditEntry) error {
+	s.reliable++
+	return s.LogSync(ctx, entry)
+}
+func (s *projectionAuditService) LogAudit(_ context.Context, entry AuditEntry) {
+	s.async++
+	s.entries = append(s.entries, entry)
+}
+
+func TestAuditListenerValidatesBindings(t *testing.T) {
+	for _, cfg := range []ListenerConfig{
+		{Bindings: []EventBinding{{Pattern: "**"}}},
+		{Bindings: []EventBinding{{Pattern: "*"}}},
+		{Bindings: []EventBinding{{Pattern: "document.created"}}},
+	} {
+		_, err := NewAuditListener(&projectionAuditService{}, zap.NewNop(), cfg)
+		require.Error(t, err)
+	}
+}
+
+func TestAuditListenerDurableProjectionPreservesEnvelopeAndErrors(t *testing.T) {
+	service := &projectionAuditService{}
+	binding := EventBinding{Pattern: "document.created", Durable: true, Projection: projectionFunc(func(eventbus.DomainEvent) (*AuditEntry, *LoginEntry, error) {
+		return &AuditEntry{Category: CategorySystem, IsSuccess: true}, nil, nil
+	})}
+	listener, err := NewAuditListener(service, zap.NewNop(), ListenerConfig{Bindings: []EventBinding{binding}})
+	require.NoError(t, err)
+	event := eventbus.DomainEvent{EventName: "document.created", EventID: "f73d80a0-dc30-4ab3-bd27-1f174e3f392f", OccurredAt: time.Now(), AuditChanges: &eventbus.AuditChangesPayload{After: map[string]any{"status": "created"}}}
+	require.NoError(t, listener.handleEvent(context.Background(), event, binding))
+	require.Len(t, service.entries, 1)
+	require.Equal(t, event.EventID, service.entries[0].EventID)
+	require.Equal(t, event.AuditChanges.After, service.entries[0].Changes.After)
+	require.True(t, service.entries[0].IsSuccess)
+	failure := errors.New("database unavailable")
+	service.failure = failure
+	require.ErrorIs(t, listener.handleEvent(context.Background(), event, binding), failure)
+	event.EventID = ""
+	require.Error(t, listener.handleEvent(context.Background(), event, binding))
+}
+
+func TestAuditListenerReliableProjectionRequiresActorAndDoesNotUseAsyncPath(t *testing.T) {
+	service := &projectionAuditService{}
+	binding := EventBinding{Pattern: "document.created", Reliable: true, Projection: projectionFunc(func(eventbus.DomainEvent) (*AuditEntry, *LoginEntry, error) {
+		return &AuditEntry{IsSuccess: true}, nil, nil
+	})}
+	listener, err := NewAuditListener(service, zap.NewNop(), ListenerConfig{Bindings: []EventBinding{binding}})
+	require.NoError(t, err)
+	event := eventbus.DomainEvent{EventName: "document.created", EventID: "f73d80a0-dc30-4ab3-bd27-1f174e3f392f", OccurredAt: time.Now()}
+	require.Error(t, listener.handleEvent(context.Background(), event, binding))
+	event.AuditMeta = &eventbus.AuditMetadataPayload{Actor: &eventbus.AuditActorSnapshotPayload{ActorType: "system"}}
+	require.NoError(t, listener.handleEvent(context.Background(), event, binding))
+	require.Equal(t, 1, service.reliable)
+	require.Zero(t, service.async)
+	require.Equal(t, event.EventID, service.entries[0].Metadata.Extra["source_event_id"])
+}
+
+func TestAuditListenerRejectsAsynchronousLoginForDurableBindings(t *testing.T) {
+	for _, reliable := range []bool{false, true} {
+		binding := EventBinding{Pattern: "session.created", Durable: !reliable, Reliable: reliable, Projection: projectionFunc(func(eventbus.DomainEvent) (*AuditEntry, *LoginEntry, error) { return nil, &LoginEntry{}, nil })}
+		listener, err := NewAuditListener(&projectionAuditService{}, zap.NewNop(), ListenerConfig{Bindings: []EventBinding{binding}})
+		require.NoError(t, err)
+		require.Error(t, listener.handleEvent(context.Background(), eventbus.DomainEvent{EventName: "session.created"}, binding))
+	}
+}