"""API Key 打码 / 写时哨兵(抄 dograh masking.py + merge.py 思路)。

- mask:返回前端时把真 key 变成 sk-****1234,真 key 永不出后端
- is_masked:判断前端回传的是不是打码占位符
- resolve_incoming_key:前端回传若是占位符 → 保留旧值;否则用新值
"""

MASK_VISIBLE_TAIL = 4


def mask(api_key: str) -> str:
    if not api_key:
        return ""
    if len(api_key) <= MASK_VISIBLE_TAIL:
        return "****"
    return f"{api_key[:2]}****{api_key[-MASK_VISIBLE_TAIL:]}"


def is_masked(value: str) -> bool:
    return "****" in (value or "")


def resolve_incoming_key(incoming: str | None, stored: str) -> str:
    """写入时决定最终 key:占位符/空 → 保留旧;否则用新。"""
    if incoming is None or incoming == "" or is_masked(incoming):
        return stored
    return incoming