feat: append-only audit trail for all mutations (P0)

backend/internal/services/appointment_service.go

@@ -12,11 +12,12 @@ import (
 )
 
 type AppointmentService struct {
-	db *sqlx.DB
+	db    *sqlx.DB
+	audit *AuditService
 }
 
-func NewAppointmentService(db *sqlx.DB) *AppointmentService {
-	return &AppointmentService{db: db}
+func NewAppointmentService(db *sqlx.DB, audit *AuditService) *AppointmentService {
+	return &AppointmentService{db: db, audit: audit}
 }
 
 type AppointmentFilter struct {
@@ -86,6 +87,7 @@ func (s *AppointmentService) Create(ctx context.Context, a *models.Appointment)
 	if err != nil {
 		return fmt.Errorf("creating appointment: %w", err)
 	}
+	s.audit.Log(ctx, "create", "appointment", &a.ID, nil, a)
 	return nil
 }
 
@@ -116,6 +118,7 @@ func (s *AppointmentService) Update(ctx context.Context, a *models.Appointment)
 	if rows == 0 {
 		return fmt.Errorf("appointment not found")
 	}
+	s.audit.Log(ctx, "update", "appointment", &a.ID, nil, a)
 	return nil
 }
 
@@ -131,5 +134,6 @@ func (s *AppointmentService) Delete(ctx context.Context, tenantID, id uuid.UUID)
 	if rows == 0 {
 		return fmt.Errorf("appointment not found")
 	}
+	s.audit.Log(ctx, "delete", "appointment", &id, nil, nil)
 	return nil
 }

backend/internal/services/audit_service.go

@@ -0,0 +1,141 @@
+package services
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"log/slog"
+
+	"github.com/google/uuid"
+	"github.com/jmoiron/sqlx"
+
+	"mgit.msbls.de/m/KanzlAI-mGMT/internal/auth"
+	"mgit.msbls.de/m/KanzlAI-mGMT/internal/models"
+)
+
+type AuditService struct {
+	db *sqlx.DB
+}
+
+func NewAuditService(db *sqlx.DB) *AuditService {
+	return &AuditService{db: db}
+}
+
+// Log records an audit entry. It extracts tenant, user, IP, and user-agent from context.
+// Errors are logged but not returned — audit logging must not break business operations.
+func (s *AuditService) Log(ctx context.Context, action, entityType string, entityID *uuid.UUID, oldValues, newValues any) {
+	tenantID, ok := auth.TenantFromContext(ctx)
+	if !ok {
+		slog.Warn("audit: missing tenant_id in context", "action", action, "entity_type", entityType)
+		return
+	}
+
+	var userID *uuid.UUID
+	if uid, ok := auth.UserFromContext(ctx); ok {
+		userID = &uid
+	}
+
+	var oldJSON, newJSON *json.RawMessage
+	if oldValues != nil {
+		if b, err := json.Marshal(oldValues); err == nil {
+			raw := json.RawMessage(b)
+			oldJSON = &raw
+		}
+	}
+	if newValues != nil {
+		if b, err := json.Marshal(newValues); err == nil {
+			raw := json.RawMessage(b)
+			newJSON = &raw
+		}
+	}
+
+	ip := auth.IPFromContext(ctx)
+	ua := auth.UserAgentFromContext(ctx)
+
+	_, err := s.db.ExecContext(ctx,
+		`INSERT INTO audit_log (tenant_id, user_id, action, entity_type, entity_id, old_values, new_values, ip_address, user_agent)
+		 VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9)`,
+		tenantID, userID, action, entityType, entityID, oldJSON, newJSON, ip, ua)
+	if err != nil {
+		slog.Error("audit: failed to write log entry",
+			"error", err,
+			"action", action,
+			"entity_type", entityType,
+			"entity_id", entityID,
+		)
+	}
+}
+
+// AuditFilter holds query parameters for listing audit log entries.
+type AuditFilter struct {
+	EntityType string
+	EntityID   *uuid.UUID
+	UserID     *uuid.UUID
+	From       string // RFC3339 date
+	To         string // RFC3339 date
+	Page       int
+	Limit      int
+}
+
+// List returns paginated audit log entries for a tenant.
+func (s *AuditService) List(ctx context.Context, tenantID uuid.UUID, filter AuditFilter) ([]models.AuditLog, int, error) {
+	if filter.Limit <= 0 {
+		filter.Limit = 50
+	}
+	if filter.Limit > 200 {
+		filter.Limit = 200
+	}
+	if filter.Page <= 0 {
+		filter.Page = 1
+	}
+	offset := (filter.Page - 1) * filter.Limit
+
+	where := "WHERE tenant_id = $1"
+	args := []any{tenantID}
+	argIdx := 2
+
+	if filter.EntityType != "" {
+		where += fmt.Sprintf(" AND entity_type = $%d", argIdx)
+		args = append(args, filter.EntityType)
+		argIdx++
+	}
+	if filter.EntityID != nil {
+		where += fmt.Sprintf(" AND entity_id = $%d", argIdx)
+		args = append(args, *filter.EntityID)
+		argIdx++
+	}
+	if filter.UserID != nil {
+		where += fmt.Sprintf(" AND user_id = $%d", argIdx)
+		args = append(args, *filter.UserID)
+		argIdx++
+	}
+	if filter.From != "" {
+		where += fmt.Sprintf(" AND created_at >= $%d", argIdx)
+		args = append(args, filter.From)
+		argIdx++
+	}
+	if filter.To != "" {
+		where += fmt.Sprintf(" AND created_at <= $%d", argIdx)
+		args = append(args, filter.To)
+		argIdx++
+	}
+
+	var total int
+	if err := s.db.GetContext(ctx, &total, "SELECT COUNT(*) FROM audit_log "+where, args...); err != nil {
+		return nil, 0, fmt.Errorf("counting audit entries: %w", err)
+	}
+
+	query := fmt.Sprintf("SELECT * FROM audit_log %s ORDER BY created_at DESC LIMIT $%d OFFSET $%d",
+		where, argIdx, argIdx+1)
+	args = append(args, filter.Limit, offset)
+
+	var entries []models.AuditLog
+	if err := s.db.SelectContext(ctx, &entries, query, args...); err != nil {
+		return nil, 0, fmt.Errorf("listing audit entries: %w", err)
+	}
+	if entries == nil {
+		entries = []models.AuditLog{}
+	}
+
+	return entries, total, nil
+}

backend/internal/services/case_service.go

@@ -13,11 +13,12 @@ import (
 )
 
 type CaseService struct {
-	db *sqlx.DB
+	db    *sqlx.DB
+	audit *AuditService
 }
 
-func NewCaseService(db *sqlx.DB) *CaseService {
-	return &CaseService{db: db}
+func NewCaseService(db *sqlx.DB, audit *AuditService) *CaseService {
+	return &CaseService{db: db, audit: audit}
 }
 
 type CaseFilter struct {
@@ -162,6 +163,9 @@ func (s *CaseService) Create(ctx context.Context, tenantID uuid.UUID, userID uui
 	if err := s.db.GetContext(ctx, &c, "SELECT * FROM cases WHERE id = $1", id); err != nil {
 		return nil, fmt.Errorf("fetching created case: %w", err)
 	}
+
+	s.audit.Log(ctx, "create", "case", &id, nil, c)
+
 	return &c, nil
 }
 
@@ -239,6 +243,9 @@ func (s *CaseService) Update(ctx context.Context, tenantID, caseID uuid.UUID, us
 	if err := s.db.GetContext(ctx, &updated, "SELECT * FROM cases WHERE id = $1", caseID); err != nil {
 		return nil, fmt.Errorf("fetching updated case: %w", err)
 	}
+
+	s.audit.Log(ctx, "update", "case", &caseID, current, updated)
+
 	return &updated, nil
 }
 
@@ -254,6 +261,7 @@ func (s *CaseService) Delete(ctx context.Context, tenantID, caseID uuid.UUID, us
 		return sql.ErrNoRows
 	}
 	createEvent(ctx, s.db, tenantID, caseID, userID, "case_archived", "Case archived", nil)
+	s.audit.Log(ctx, "delete", "case", &caseID, map[string]string{"status": "active"}, map[string]string{"status": "archived"})
 	return nil
 }
 

backend/internal/services/deadline_service.go

@@ -1,6 +1,7 @@
 package services
 
 import (
+	"context"
 	"database/sql"
 	"fmt"
 	"time"
@@ -13,12 +14,13 @@ import (
 
 // DeadlineService handles CRUD operations for case deadlines
 type DeadlineService struct {
-	db *sqlx.DB
+	db    *sqlx.DB
+	audit *AuditService
 }
 
 // NewDeadlineService creates a new deadline service
-func NewDeadlineService(db *sqlx.DB) *DeadlineService {
-	return &DeadlineService{db: db}
+func NewDeadlineService(db *sqlx.DB, audit *AuditService) *DeadlineService {
+	return &DeadlineService{db: db, audit: audit}
 }
 
 // ListAll returns all deadlines for a tenant, ordered by due_date
@@ -87,7 +89,7 @@ type CreateDeadlineInput struct {
 }
 
 // Create inserts a new deadline
-func (s *DeadlineService) Create(tenantID uuid.UUID, input CreateDeadlineInput) (*models.Deadline, error) {
+func (s *DeadlineService) Create(ctx context.Context, tenantID uuid.UUID, input CreateDeadlineInput) (*models.Deadline, error) {
 	id := uuid.New()
 	source := input.Source
 	if source == "" {
@@ -108,6 +110,7 @@ func (s *DeadlineService) Create(tenantID uuid.UUID, input CreateDeadlineInput)
 	if err != nil {
 		return nil, fmt.Errorf("creating deadline: %w", err)
 	}
+	s.audit.Log(ctx, "create", "deadline", &id, nil, d)
 	return &d, nil
 }
 
@@ -123,7 +126,7 @@ type UpdateDeadlineInput struct {
 }
 
 // Update modifies an existing deadline
-func (s *DeadlineService) Update(tenantID, deadlineID uuid.UUID, input UpdateDeadlineInput) (*models.Deadline, error) {
+func (s *DeadlineService) Update(ctx context.Context, tenantID, deadlineID uuid.UUID, input UpdateDeadlineInput) (*models.Deadline, error) {
 	// First check it exists and belongs to tenant
 	existing, err := s.GetByID(tenantID, deadlineID)
 	if err != nil {
@@ -154,11 +157,12 @@ func (s *DeadlineService) Update(tenantID, deadlineID uuid.UUID, input UpdateDea
 	if err != nil {
 		return nil, fmt.Errorf("updating deadline: %w", err)
 	}
+	s.audit.Log(ctx, "update", "deadline", &deadlineID, existing, d)
 	return &d, nil
 }
 
 // Complete marks a deadline as completed
-func (s *DeadlineService) Complete(tenantID, deadlineID uuid.UUID) (*models.Deadline, error) {
+func (s *DeadlineService) Complete(ctx context.Context, tenantID, deadlineID uuid.UUID) (*models.Deadline, error) {
 	query := `UPDATE deadlines SET
 	            status = 'completed',
 	            completed_at = $1,
@@ -176,11 +180,12 @@ func (s *DeadlineService) Complete(tenantID, deadlineID uuid.UUID) (*models.Dead
 		}
 		return nil, fmt.Errorf("completing deadline: %w", err)
 	}
+	s.audit.Log(ctx, "update", "deadline", &deadlineID, map[string]string{"status": "pending"}, map[string]string{"status": "completed"})
 	return &d, nil
 }
 
 // Delete removes a deadline
-func (s *DeadlineService) Delete(tenantID, deadlineID uuid.UUID) error {
+func (s *DeadlineService) Delete(ctx context.Context, tenantID, deadlineID uuid.UUID) error {
 	query := `DELETE FROM deadlines WHERE id = $1 AND tenant_id = $2`
 	result, err := s.db.Exec(query, deadlineID, tenantID)
 	if err != nil {
@@ -193,5 +198,6 @@ func (s *DeadlineService) Delete(tenantID, deadlineID uuid.UUID) error {
 	if rows == 0 {
 		return fmt.Errorf("deadline not found")
 	}
+	s.audit.Log(ctx, "delete", "deadline", &deadlineID, nil, nil)
 	return nil
 }

backend/internal/services/document_service.go

@@ -18,10 +18,11 @@ const documentBucket = "kanzlai-documents"
 type DocumentService struct {
 	db      *sqlx.DB
 	storage *StorageClient
+	audit   *AuditService
 }
 
-func NewDocumentService(db *sqlx.DB, storage *StorageClient) *DocumentService {
-	return &DocumentService{db: db, storage: storage}
+func NewDocumentService(db *sqlx.DB, storage *StorageClient, audit *AuditService) *DocumentService {
+	return &DocumentService{db: db, storage: storage, audit: audit}
 }
 
 type CreateDocumentInput struct {
@@ -97,6 +98,7 @@ func (s *DocumentService) Create(ctx context.Context, tenantID, caseID, userID u
 	if err := s.db.GetContext(ctx, &doc, "SELECT * FROM documents WHERE id = $1", id); err != nil {
 		return nil, fmt.Errorf("fetching created document: %w", err)
 	}
+	s.audit.Log(ctx, "create", "document", &id, nil, doc)
 	return &doc, nil
 }
 
@@ -151,6 +153,7 @@ func (s *DocumentService) Delete(ctx context.Context, tenantID, docID, userID uu
 	// Log case event
 	createEvent(ctx, s.db, tenantID, doc.CaseID, userID, "document_deleted",
 		fmt.Sprintf("Document deleted: %s", doc.Title), nil)
+	s.audit.Log(ctx, "delete", "document", &docID, doc, nil)
 
 	return nil
 }

backend/internal/services/note_service.go

@@ -13,11 +13,12 @@ import (
 )
 
 type NoteService struct {
-	db *sqlx.DB
+	db    *sqlx.DB
+	audit *AuditService
 }
 
-func NewNoteService(db *sqlx.DB) *NoteService {
-	return &NoteService{db: db}
+func NewNoteService(db *sqlx.DB, audit *AuditService) *NoteService {
+	return &NoteService{db: db, audit: audit}
 }
 
 // ListByParent returns all notes for a given parent entity, scoped to tenant.
@@ -68,6 +69,7 @@ func (s *NoteService) Create(ctx context.Context, tenantID uuid.UUID, createdBy
 	if err != nil {
 		return nil, fmt.Errorf("creating note: %w", err)
 	}
+	s.audit.Log(ctx, "create", "note", &id, nil, n)
 	return &n, nil
 }
 
@@ -85,6 +87,7 @@ func (s *NoteService) Update(ctx context.Context, tenantID, noteID uuid.UUID, co
 		}
 		return nil, fmt.Errorf("updating note: %w", err)
 	}
+	s.audit.Log(ctx, "update", "note", &noteID, nil, n)
 	return &n, nil
 }
 
@@ -101,6 +104,7 @@ func (s *NoteService) Delete(ctx context.Context, tenantID, noteID uuid.UUID) er
 	if rows == 0 {
 		return fmt.Errorf("note not found")
 	}
+	s.audit.Log(ctx, "delete", "note", &noteID, nil, nil)
 	return nil
 }
 

backend/internal/services/party_service.go

@@ -13,11 +13,12 @@ import (
 )
 
 type PartyService struct {
-	db *sqlx.DB
+	db    *sqlx.DB
+	audit *AuditService
 }
 
-func NewPartyService(db *sqlx.DB) *PartyService {
-	return &PartyService{db: db}
+func NewPartyService(db *sqlx.DB, audit *AuditService) *PartyService {
+	return &PartyService{db: db, audit: audit}
 }
 
 type CreatePartyInput struct {
@@ -79,6 +80,7 @@ func (s *PartyService) Create(ctx context.Context, tenantID, caseID uuid.UUID, u
 	if err := s.db.GetContext(ctx, &party, "SELECT * FROM parties WHERE id = $1", id); err != nil {
 		return nil, fmt.Errorf("fetching created party: %w", err)
 	}
+	s.audit.Log(ctx, "create", "party", &id, nil, party)
 	return &party, nil
 }
 
@@ -135,6 +137,7 @@ func (s *PartyService) Update(ctx context.Context, tenantID, partyID uuid.UUID,
 	if err := s.db.GetContext(ctx, &updated, "SELECT * FROM parties WHERE id = $1", partyID); err != nil {
 		return nil, fmt.Errorf("fetching updated party: %w", err)
 	}
+	s.audit.Log(ctx, "update", "party", &partyID, current, updated)
 	return &updated, nil
 }
 
@@ -148,5 +151,6 @@ func (s *PartyService) Delete(ctx context.Context, tenantID, partyID uuid.UUID)
 	if rows == 0 {
 		return sql.ErrNoRows
 	}
+	s.audit.Log(ctx, "delete", "party", &partyID, nil, nil)
 	return nil
 }

backend/internal/services/tenant_service.go

@@ -13,11 +13,12 @@ import (
 )
 
 type TenantService struct {
-	db *sqlx.DB
+	db    *sqlx.DB
+	audit *AuditService
 }
 
-func NewTenantService(db *sqlx.DB) *TenantService {
-	return &TenantService{db: db}
+func NewTenantService(db *sqlx.DB, audit *AuditService) *TenantService {
+	return &TenantService{db: db, audit: audit}
 }
 
 // Create creates a new tenant and assigns the creator as owner.
@@ -49,6 +50,7 @@ func (s *TenantService) Create(ctx context.Context, userID uuid.UUID, name, slug
 		return nil, fmt.Errorf("commit: %w", err)
 	}
 
+	s.audit.Log(ctx, "create", "tenant", &tenant.ID, nil, tenant)
 	return &tenant, nil
 }
 
@@ -184,6 +186,7 @@ func (s *TenantService) InviteByEmail(ctx context.Context, tenantID uuid.UUID, e
 		return nil, fmt.Errorf("invite user: %w", err)
 	}
 
+	s.audit.Log(ctx, "create", "membership", &tenantID, nil, ut)
 	return &ut, nil
 }
 
@@ -199,6 +202,7 @@ func (s *TenantService) UpdateSettings(ctx context.Context, tenantID uuid.UUID,
 	if err != nil {
 		return nil, fmt.Errorf("update settings: %w", err)
 	}
+	s.audit.Log(ctx, "update", "settings", &tenantID, nil, settings)
 	return &tenant, nil
 }
 
@@ -236,5 +240,6 @@ func (s *TenantService) RemoveMember(ctx context.Context, tenantID, userID uuid.
 		return fmt.Errorf("remove member: %w", err)
 	}
 
+	s.audit.Log(ctx, "delete", "membership", &tenantID, map[string]any{"user_id": userID, "role": role}, nil)
 	return nil
 }