"""API key masking for safe logging and display.

API keys must never appear in plaintext in logs, stack traces, or
debug output. This module provides ``mask_api_key`` which preserves
enough of the key for identification (prefix and suffix) while hiding
the secret portion.

Example::

    >>> mask_api_key("st_recon_abc123def456x4Rq")
    'st_recon_...x4Rq'
"""

from __future__ import annotations

_PREFIX_LEN = 8
_SUFFIX_LEN = 4
_MIN_MASK_LEN = _PREFIX_LEN + _SUFFIX_LEN + 1


def mask_api_key(key: str) -> str:
    """Mask an API key for safe logging.

    Preserves the first 8 characters (typically the key type prefix like
    ``st_recon``) and the last 4 characters for identification, replacing
    the middle with ``...``.

    Keys shorter than 13 characters are fully masked to ``***`` since
    there is not enough material to show both prefix and suffix safely.

    Args:
        key: The plaintext API key.

    Returns:
        A masked string safe for logging and display.
    """
    if len(key) < _MIN_MASK_LEN:
        return "***"
    return f"{key[:_PREFIX_LEN]}...{key[-_SUFFIX_LEN:]}"
