# [DEF:backend.src.core.auth.logger:Module]
#
# @TIER:      STANDARD
# @SEMANTICS: auth, logger, audit, security
# @PURPOSE:   Audit logging for security-related events.
# @LAYER:     Core
# @RELATION:  USES -> backend.src.core.logger.belief_scope
#
# @INVARIANT: Must not log sensitive data like passwords or full tokens.

# [SECTION: IMPORTS]
from ..logger import logger, belief_scope
from datetime import datetime
# [/SECTION]

# [DEF:log_security_event:Function]
# @PURPOSE: Logs a security-related event for audit trails.
# @PRE:     event_type and username are strings.
# @POST:    Security event is written to the application log.
# @PARAM:   event_type (str) - Type of event (e.g., LOGIN_SUCCESS, PERMISSION_DENIED).
# @PARAM:   username (str) - The user involved in the event.
# @PARAM:   details (dict) - Additional non-sensitive metadata.
def log_security_event(event_type: str, username: str, details: dict = None):
    with belief_scope("log_security_event", f"{event_type}:{username}"):
        timestamp = datetime.utcnow().isoformat()
        msg = f"[AUDIT][{timestamp}][{event_type}] User: {username}"
        if details:
            msg += f" Details: {details}"
        logger.info(msg)
# [/DEF:log_security_event:Function]

# [/DEF:backend.src.core.auth.logger:Module]