query-orchestration/internal/usermanagement/audit.go

// audit.go provides comprehensive audit trail logging functionality for user management operations.
// This package uses structured logging with log/slog and supports tagging audit events for filtering
// in CloudWatch and other log aggregation systems. Audit logs can be queried using the "audit" tag.
package usermanagement

import (
	"log/slog"
)

// ActionType represents the type of action being logged in the audit trail.
type ActionType string

const (
	// ActionCreate represents a user creation action
	ActionCreate ActionType = "CREATE"
	// ActionDelete represents a user deletion action
	ActionDelete ActionType = "DELETE"
	// ActionDisable represents a user disable action
	ActionDisable ActionType = "DISABLE"
	// ActionEnable represents a user enable action
	ActionEnable ActionType = "ENABLE"
	// ActionUpdate represents a user update action
	ActionUpdate ActionType = "UPDATE"
	// ActionAssignRole represents a role assignment action
	ActionAssignRole ActionType = "ASSIGN_ROLE"
	// ActionUnassignRole represents a role unassignment action
	ActionUnassignRole ActionType = "UNASSIGN_ROLE"
)

// SystemType represents the system where the action occurred.
type SystemType string

const (
	// SystemCognito represents AWS Cognito system
	SystemCognito SystemType = "COGNITO"
	// SystemPermit represents Permit.io system
	SystemPermit SystemType = "PERMIT"
)

// ResultType represents the outcome of the action.
type ResultType string

const (
	// ResultSuccess represents a successful action
	ResultSuccess ResultType = "SUCCESS"
	// ResultFailure represents a failed action
	ResultFailure ResultType = "FAILURE"
)

// LogUserAdminAction logs a user management action to the audit trail with the "audit" tag.
// This function should be used for all user creation, deletion, update, disable, and enable operations.
//
// Parameters:
//   - logger: The slog.Logger instance to use for logging
//   - action: The type of action being performed
//   - system: The system where the action occurred (Cognito or Permit.io)
//   - adminUser: The email or identifier of the admin performing the action
//   - targetUser: The email or identifier of the user being acted upon
//   - subjectID: The Cognito Subject ID of the target user (optional, use empty string if not applicable)
//   - result: The result of the action (success or failure)
//   - details: Additional details or error messages about the action
//   - requestID: The request ID for correlation (optional, use empty string if not applicable)
func LogUserAdminAction(logger *slog.Logger, action ActionType, system SystemType, adminUser, targetUser, subjectID string, result ResultType, details, requestID string) {
	attrs := []interface{}{
		"audit", true,
		"audit_type", "user_admin",
		"action", action,
		"system", system,
		"admin_user", adminUser,
		"target_user", targetUser,
		"result", result,
		"details", details,
	}

	// Add optional fields if they are not empty
	if subjectID != "" {
		attrs = append(attrs, "cognito_subject_id", subjectID)
	}
	if requestID != "" {
		attrs = append(attrs, "request_id", requestID)
	}

	logger.Info("user_admin_action", attrs...)
}

// LogRoleAdminAction logs a role management action to the audit trail with the "audit" tag.
// This function should be used for all role assignment and unassignment operations.
//
// Parameters:
//   - logger: The slog.Logger instance to use for logging
//   - action: The type of action being performed (assign or unassign role)
//   - adminUser: The email or identifier of the admin performing the action
//   - targetUser: The email or identifier of the user whose role is being modified
//   - role: The role being assigned or unassigned
//   - result: The result of the action (success or failure)
//   - details: Additional details or error messages about the action
//   - requestID: The request ID for correlation (optional, use empty string if not applicable)
func LogRoleAdminAction(logger *slog.Logger, action ActionType, adminUser, targetUser, role string, result ResultType, details, requestID string) {
	attrs := []interface{}{
		"audit", true,
		"audit_type", "role_admin",
		"action", action,
		"system", SystemPermit,
		"admin_user", adminUser,
		"target_user", targetUser,
		"role", role,
		"result", result,
		"details", details,
	}

	// Add optional fields if they are not empty
	if requestID != "" {
		attrs = append(attrs, "request_id", requestID)
	}

	logger.Info("role_admin_action", attrs...)
}

// LogUserListAction logs a user list/query action to the audit trail with the "audit" tag.
// This function should be used when administrators query or list users.
//
// Parameters:
//   - logger: The slog.Logger instance to use for logging
//   - adminUser: The email or identifier of the admin performing the query
//   - filters: Description of any filters applied to the query
//   - resultCount: Number of results returned
//   - requestID: The request ID for correlation (optional, use empty string if not applicable)
func LogUserListAction(logger *slog.Logger, adminUser, filters string, resultCount int, requestID string) {
	attrs := []interface{}{
		"audit", true,
		"audit_type", "user_query",
		"action", "LIST",
		"admin_user", adminUser,
		"filters", filters,
		"result_count", resultCount,
	}

	// Add optional fields if they are not empty
	if requestID != "" {
		attrs = append(attrs, "request_id", requestID)
	}

	logger.Info("user_list_action", attrs...)
}