"""Brand-aware Redis cache key helpers.

Phase 4E of the multi-brand isolation work introduced brand-prefixing for
every Redis key whose suffix is a user-supplied string. The same ``phone`` or
``account`` value belonging to two different brands must not collide on a
shared Redis instance.

Each helper returns the canonical key. The pre-Phase-4E ``user-session-{account}``
form (and its dual-read fallback) was removed in the
``2026-05-05-phase-4e-dual-read-sunset.md`` cleanup -- writers and readers now
both use the brand-prefixed form exclusively.
"""

from __future__ import annotations


def sms_captcha_key(brand_id: int, phone: str) -> str:
    """Redis key for the image captcha that gates SMS issuance."""
    return f"sms_captcha:brand:{brand_id}:{phone}"


def login_wrong_key(brand_id: int, account: str) -> str:
    """Redis key for the wrong-password counter used to lock accounts."""
    return f"user-login-wrong:brand:{brand_id}:{account}"


def register_sms_key(brand_id: int, tel: str) -> str:
    """Redis key for the registration SMS code."""
    return f"user-register-sms:brand:{brand_id}:{tel}"


def register_sms_rate_key(brand_id: int, tel: str) -> str:
    """Redis key for the registration SMS resend throttle."""
    return f"user-register-sms-rate:brand:{brand_id}:{tel}"


def session_key(brand_id: int, account: str) -> str:
    """Redis key for the active session id of a player."""
    return f"user-session:brand:{brand_id}:{account}"


async def read_session_id(redis, brand_id: int, account: str):
    """Look up the active session id for ``(brand_id, account)``."""
    return await redis.get(session_key(brand_id, account))