"""
Development authentication utilities for StarPunk

WARNING: These functions provide authentication bypass for local development.
They should ONLY be used when DEV_MODE=true.

This module contains utilities that should never be used in production.
"""

import logging
from flask import current_app
from starpunk.auth import create_session


logger = logging.getLogger(__name__)


def is_dev_mode() -> bool:
    """
    Check if development mode is enabled

    Returns:
        bool: True if DEV_MODE is explicitly set to True, False otherwise

    Security:
        This function is used to guard all development authentication features.
        It explicitly checks for True (not just truthy values).
    """
    return current_app.config.get("DEV_MODE", False) is True


def create_dev_session(me: str) -> str:
    """
    Create a development session without authentication

    WARNING: This creates an authenticated session WITHOUT any verification.
    Only call this function after verifying is_dev_mode() returns True.

    Args:
        me: The identity URL to create a session for (typically DEV_ADMIN_ME)

    Returns:
        str: Session token for the created session

    Raises:
        ValueError: If me is empty or invalid

    Logs:
        WARNING: Logs that dev authentication was used (for security audit trail)

    Security:
        - Should only be called when DEV_MODE=true
        - Logs warning on every use
        - Uses same session creation as production (just skips auth)
    """
    if not me:
        raise ValueError("Identity (me) is required")

    # Log security warning
    logger.warning(
        f"DEV MODE: Creating session for {me} WITHOUT authentication. "
        "This should NEVER happen in production!"
    )

    # Create session using production session creation
    # This ensures dev sessions work exactly like production sessions
    session_token = create_session(me)

    return session_token