"""
DM Pairing System

Code-based approval flow for authorizing new users on messaging platforms:
unknown users receive a one-time pairing code that the bot owner approves via
the CLI, instead of maintaining static user-ID allowlists.

Security properties (OWASP + NIST SP 800-63-4): 8-char codes from a 32-char
unambiguous alphabet via ``secrets``, 1-hour expiry, max 3 pending per
platform, 1 request per user per 10 min, lockout after 5 failed approvals,
chmod 0600 data files, codes never logged. Storage: ~/.hermes/pairing/
"""

import contextlib
import hashlib
import json
import logging
import os
import secrets
import tempfile
import threading
import time
from pathlib import Path
from typing import Optional

from gateway.whatsapp_identity import (
    expand_whatsapp_aliases,
    normalize_whatsapp_identifier,
)
from hermes_constants import (
    get_default_hermes_root,
    get_hermes_dir,
    get_hermes_home,
)
from utils import atomic_replace

logger = logging.getLogger(__name__)


# Unambiguous alphabet -- excludes 0/O, 1/I to prevent confusion
ALPHABET = "ABCDEFGHJKLMNPQRSTUVWXYZ23456789"
CODE_LENGTH = 8

CODE_TTL_SECONDS = 3600             # Codes expire after 1 hour
RATE_LIMIT_SECONDS = 600            # 1 request per user per 10 minutes
LOCKOUT_SECONDS = 3600              # Lockout duration after too many failures
MAX_PENDING_PER_PLATFORM = 3        # Max pending codes per platform
MAX_FAILED_ATTEMPTS = 5             # Failed approvals before lockout

# Default (non-profile-scoped) pairing directory. Deliberately ``None``: the
# long-lived gateway imports this module at boot, and an eagerly computed path
# would freeze whatever HERMES_HOME/profile context existed then, ignoring later
# context-local overrides (hermes_constants.set_hermes_home_override) -- so the
# gateway and the short-lived ``hermes pairing`` CLI ended up writing different
# directories. ``_default_pairing_dir()`` resolves fresh on every call; tests
# patch this attribute to a concrete path (``patch("gateway.pairing.PAIRING_DIR", tmp)``)
# and a non-``None`` value takes precedence.
PAIRING_DIR = None


def _default_pairing_dir() -> Path:
    """Resolve the default pairing directory fresh (see ``PAIRING_DIR``)."""
    if PAIRING_DIR is not None:
        return PAIRING_DIR
    return get_hermes_dir("platforms/pairing", "pairing")


# Platform value -> per-platform allowlist env var. When an operator already
# runs an allowlist for a platform, approving a pairing code also writes the
# user into it (and revoking removes them), so the operator's list stays the
# single visible source of truth instead of drifting from an opaque
# approved.json. Platforms absent here (or with no allowlist configured) keep
# the pairing store as the sole grant record, honored by the authz union.
_PLATFORM_ALLOWLIST_ENV = {
    "telegram": "TELEGRAM_ALLOWED_USERS",
    "discord": "DISCORD_ALLOWED_USERS",
    "whatsapp": "WHATSAPP_ALLOWED_USERS",
    "whatsapp_cloud": "WHATSAPP_CLOUD_ALLOWED_USERS",
    "slack": "SLACK_ALLOWED_USERS",
    "signal": "SIGNAL_ALLOWED_USERS",
    "email": "EMAIL_ALLOWED_USERS",
    "sms": "SMS_ALLOWED_USERS",
    "mattermost": "MATTERMOST_ALLOWED_USERS",
    "matrix": "MATRIX_ALLOWED_USERS",
    "dingtalk": "DINGTALK_ALLOWED_USERS",
    "feishu": "FEISHU_ALLOWED_USERS",
    "wecom": "WECOM_ALLOWED_USERS",
    "wecom_callback": "WECOM_CALLBACK_ALLOWED_USERS",
    "weixin": "WEIXIN_ALLOWED_USERS",
    "bluebubbles": "BLUEBUBBLES_ALLOWED_USERS",
    "qqbot": "QQ_ALLOWED_USERS",
    "yuanbao": "YUANBAO_ALLOWED_USERS",
}


def _allowlist_env_for_platform(platform: str) -> Optional[str]:
    """Allowlist env var name for ``platform`` (plugin registry fallback), or None."""
    platform = (platform or "").lower().strip()
    env_var = _PLATFORM_ALLOWLIST_ENV.get(platform)
    if env_var:
        return env_var
    try:
        from gateway.platform_registry import platform_registry

        entry = platform_registry.get(platform)
        if entry and entry.allowed_users_env:
            return entry.allowed_users_env
    except Exception:
        pass
    return None


def _split_allowlist(raw: str) -> list:
    return [uid.strip() for uid in raw.split(",") if uid.strip()]


def _platform_uses_whatsapp_identity(platform: str) -> bool:
    """True for Baileys WhatsApp and Meta Cloud — same phone/JID identity rules."""
    return (platform or "").strip().lower() in {"whatsapp", "whatsapp_cloud"}


def _normalize_user_id(platform: str, user_id: str) -> str:
    """Normalize platform-specific user IDs before persisting / comparing them."""
    raw_user_id = str(user_id or "").strip()
    if _platform_uses_whatsapp_identity(platform):
        return normalize_whatsapp_identifier(raw_user_id) or raw_user_id
    return raw_user_id


def _user_id_aliases(platform: str, user_id: str) -> set[str]:
    """Return all known equivalent user IDs for auth / allowlist matching."""
    raw_user_id = str(user_id or "").strip()
    if not raw_user_id:
        return set()

    aliases = {raw_user_id, _normalize_user_id(platform, raw_user_id)}
    if _platform_uses_whatsapp_identity(platform):
        aliases.update(expand_whatsapp_aliases(raw_user_id))
    aliases.discard("")
    return aliases


def _user_ids_match(platform: str, left: str, right: str) -> bool:
    """Return True when two user IDs represent the same principal."""
    left_aliases = _user_id_aliases(platform, left)
    right_aliases = _user_id_aliases(platform, right)
    return bool(left_aliases and right_aliases and (left_aliases & right_aliases))


def _read_allowlist_env(env_var: str) -> str:
    """Read a platform allowlist env var through the profile secret scope.

    Under multiplexing the process env may hold ANOTHER profile's allowlist
    (first-writer-wins YAML→env bridges), so a scoped miss must return empty
    rather than borrow the process value. Unscoped callers (single-profile
    CLI / admin endpoints) keep the legacy ``os.getenv`` read. Writes go
    through ``hermes_cli.config.save_env_value`` / ``remove_env_value``, which
    target the active profile's ``.env`` and, under multiplexing, publish into
    the installed scope mapping rather than the shared ``os.environ``.
    """
    try:
        from agent.secret_scope import UnscopedSecretError, get_secret

        try:
            return (get_secret(env_var) or "").strip()
        except UnscopedSecretError:
            pass
    except Exception:
        pass
    return (os.getenv(env_var) or "").strip()


def _configured_allowlist(platform: str):
    """Return ``(env_var, ids)`` for a platform whose allowlist is configured, else None.

    An unconfigured allowlist means an open gateway: the pairing store stays the
    sole grant record and we must never lock the gateway by materializing one.
    """
    env_var = _allowlist_env_for_platform(platform)
    if not env_var:
        return None
    current = _read_allowlist_env(env_var)
    if not current:
        return None
    return env_var, _split_allowlist(current)


def _sync_allowlist_add(platform: str, user_id: str) -> None:
    """Add ``user_id`` to the platform allowlist env var IF one is configured."""
    configured = _configured_allowlist(platform)
    if configured is None:
        return
    env_var, ids = configured
    if "*" in ids or str(user_id) in ids:
        return  # Already covered.
    ids.append(str(user_id))
    try:
        from hermes_cli.config import save_env_value

        save_env_value(env_var, ",".join(ids))
    except Exception:
        # Best-effort: the pairing store grant still authorizes via the union.
        pass


def _iter_live_gateway_adapters():
    """Yield adapters from the in-process GatewayRunner, if one is running."""
    try:
        from gateway.run import _gateway_runner_ref

        runner = _gateway_runner_ref()
    except Exception:
        return
    if runner is None:
        return
    for adapter in (getattr(runner, "adapters", None) or {}).values():
        if adapter is not None:
            yield adapter
    for mapping in (getattr(runner, "_profile_adapters", None) or {}).values():
        for adapter in (mapping or {}).values():
            if adapter is not None:
                yield adapter


def _adapter_platform_name(adapter) -> str:
    value = getattr(getattr(adapter, "platform", None), "value", None)
    if value:
        return str(value).strip().lower()
    return str(getattr(adapter, "name", None) or "").strip().lower()


def _purge_allowlist_entries(entries, platform: str, user_id: str):
    """Drop alias-equivalent allowlist entries while preserving ``*``."""
    def keep(entry) -> bool:
        entry = str(entry)
        return entry.strip() == "*" or not _user_ids_match(platform, entry, str(user_id))

    if isinstance(entries, str):
        return ",".join(part for part in _split_allowlist(entries) if keep(part))
    if isinstance(entries, (set, frozenset)):
        return {entry for entry in entries if keep(entry)}
    if isinstance(entries, (list, tuple)):
        return [entry for entry in entries if keep(entry)]
    return entries


def _sync_live_adapter_allowlist_remove(platform: str, user_id: str) -> None:
    """Clear revoked principals from in-process adapter allowlist snapshots.

    Adapters snapshot ``_allow_from`` at construction; when the revoked
    principal was the sole entry the env key is removed entirely, so intake
    must not keep authorizing from the stale snapshot until restart.
    """
    platform_name = (platform or "").strip().lower()
    if not platform_name or not str(user_id or "").strip():
        return
    for adapter in _iter_live_gateway_adapters():
        if _adapter_platform_name(adapter) != platform_name:
            continue
        if hasattr(adapter, "_allow_from"):
            with contextlib.suppress(Exception):
                adapter._allow_from = _purge_allowlist_entries(
                    set(adapter._allow_from or ()), platform_name, user_id
                )
        extra = getattr(getattr(adapter, "config", None), "extra", None)
        if isinstance(extra, dict) and "allow_from" in extra:
            with contextlib.suppress(Exception):
                extra["allow_from"] = _purge_allowlist_entries(
                    extra.get("allow_from"), platform_name, user_id
                )


def _sync_allowlist_remove(platform: str, user_id: str) -> None:
    """Remove ``user_id`` (and WhatsApp alias equivalents) from the allowlist.

    Approve mirrors a normalized phone while revoke is often given a JID or
    device-suffix form, so matching uses alias rules -- exact-string delete
    would leave the sender authorized. Also clears in-process adapter
    snapshots so sole-entry revocation works without a gateway restart.
    """
    configured = _configured_allowlist(platform)
    if configured is None:
        return  # No allowlist configured — do not touch config-only snapshots.
    env_var, ids = configured
    remaining = _purge_allowlist_entries(ids, platform, user_id)
    if len(remaining) == len(ids):
        return  # Not present.
    try:
        from hermes_cli.config import save_env_value, remove_env_value

        if remaining:
            save_env_value(env_var, ",".join(remaining))
        else:
            remove_env_value(env_var)
    except Exception:
        pass
    _sync_live_adapter_allowlist_remove(platform, user_id)


def _load_json_file(path: Path) -> dict:
    if path.exists():
        try:
            data = json.loads(path.read_text(encoding="utf-8"))
            return data if isinstance(data, dict) else {}
        except (json.JSONDecodeError, OSError):
            return {}
    return {}


def _merge_pairing_dir(active_dir: Path, alternate_dir: Path) -> None:
    """Merge split legacy (``pairing``) / new (``platforms/pairing``) data into the active dir.

    If both exist, approved users in the inactive location must not be
    silently ignored (they would be asked for a fresh code).
    """
    if not alternate_dir.exists() or active_dir.resolve() == alternate_dir.resolve():
        return
    active_dir.mkdir(parents=True, exist_ok=True)
    for src in alternate_dir.glob("*.json"):
        if not src.is_file():
            continue
        dest = active_dir / src.name
        merged = _load_json_file(src)
        if not merged:
            continue
        current = _load_json_file(dest)
        before = dict(current)
        # Active data wins on key conflict; otherwise union the inactive data.
        merged.update(current)
        if merged != before:
            _secure_write(dest, json.dumps(merged, indent=2, ensure_ascii=False))


def _migrate_split_pairing_dirs(
    *,
    home: Optional[Path] = None,
    active: Optional[Path] = None,
) -> None:
    home = home or get_hermes_home()
    old_dir = home / "pairing"
    new_dir = home / "platforms" / "pairing"
    active = active if active is not None else _default_pairing_dir()
    alternate = new_dir if active.resolve() == old_dir.resolve() else old_dir
    _merge_pairing_dir(active, alternate)


def _secure_write(path: Path, data: str) -> None:
    """Write 0600 via temp file + atomic rename so readers never see a partial file."""
    path.parent.mkdir(parents=True, exist_ok=True)
    fd, tmp_path = tempfile.mkstemp(dir=str(path.parent), suffix=".tmp")
    try:
        with os.fdopen(fd, "w", encoding="utf-8") as f:
            f.write(data)
            f.flush()
            os.fsync(f.fileno())
        atomic_replace(tmp_path, path)
        with contextlib.suppress(OSError):  # Windows doesn't support chmod the same way
            os.chmod(path, 0o600)
    except BaseException:
        with contextlib.suppress(OSError):
            os.unlink(tmp_path)
        raise


class PairingStore:
    """
    Manages pairing codes and approved user lists.

    Data files per platform: ``{platform}-pending.json``,
    ``{platform}-approved.json``, plus shared ``_rate_limits.json``.

    With ``profile="<name>"`` storage resolves from that profile's own
    HERMES_HOME with the same legacy/consolidated layout rules as
    ``hermes -p <name> pairing ...``, so multiplex gateways and profile-scoped
    CLI approvals share one whitelist. Without a profile, storage is the global
    pairing directory for the current HERMES_HOME.
    """

    def __init__(self, profile: Optional[str] = None):
        # Resolved lazily: tests use a temp HERMES_HOME and may construct the
        # store before the env is set.
        if profile:
            root = get_default_hermes_root()
            profile_home = root if profile == "default" else root / "profiles" / profile
            self._dir = get_hermes_dir("platforms/pairing", "pairing", home=profile_home)
        else:
            profile_home = None
            self._dir = _default_pairing_dir()
        self._dir.mkdir(parents=True, exist_ok=True)
        # Merge the alternate old/new layout so upgrades cannot split approvals;
        # a profile store must resolve exactly as ``hermes -p <profile>`` does.
        _migrate_split_pairing_dirs(home=profile_home, active=self._dir)
        # Protects all read-modify-write cycles: platform adapters run
        # concurrently in threads sharing one PairingStore.
        self._lock = threading.RLock()
        self._profile = profile  # for diagnostics / log lines

    @property
    def profile(self) -> Optional[str]:
        """Profile name this store is scoped to, or None for the global store."""
        return self._profile

    def _pending_path(self, platform: str) -> Path:
        return self._dir / f"{platform}-pending.json"

    def _approved_path(self, platform: str) -> Path:
        return self._dir / f"{platform}-approved.json"

    def _rate_limit_path(self) -> Path:
        return self._dir / "_rate_limits.json"

    def _load_json(self, path: Path) -> dict:
        if path.exists():
            try:
                return json.loads(path.read_text(encoding="utf-8"))
            except PermissionError as e:
                # Loud warning: a 0600 file owned by another uid (Docker:
                # `docker exec` as root writes it, the gosu-dropped gateway
                # can't read it) would otherwise be swallowed by the OSError
                # branch and silently leave the user unauthorized.
                try:
                    st = path.stat()
                    owner_info = f"owner_uid={st.st_uid} mode={oct(st.st_mode)[-4:]}"
                except OSError:
                    owner_info = "<stat failed>"
                euid = os.geteuid() if hasattr(os, "geteuid") else "n/a"  # no geteuid on Windows
                logger.warning(
                    "Pairing file %s exists but is not readable as uid=%s (%s; %s). "
                    "If you ran `docker exec <container> hermes pairing approve ...` as root, "
                    "re-run with `docker exec -u hermes <container> ...` and "
                    "chown the existing file to the hermes user, or restart the "
                    "container so the entrypoint can fix ownership.",
                    path, euid, owner_info, e,
                )
                return {}
            except (json.JSONDecodeError, OSError):
                return {}
        return {}

    def _save_json(self, path: Path, data: dict) -> None:
        _secure_write(path, json.dumps(data, indent=2, ensure_ascii=False))

    # ----- Approved users -----

    def is_approved(self, platform: str, user_id: str) -> bool:
        """Check if a user is approved (paired) on a platform."""
        approved = self._load_json(self._approved_path(platform))
        return any(_user_ids_match(platform, uid, user_id) for uid in approved)

    def list_approved(self, platform: str = None) -> list:
        """List approved users, optionally filtered by platform."""
        results = []
        platforms = [platform] if platform else self._all_platforms("approved")
        for p in platforms:
            approved = self._load_json(self._approved_path(p))
            for uid, info in approved.items():
                results.append({"platform": p, "user_id": uid, **info})
        return results

    def _approve_user(self, platform: str, user_id: str, user_name: str = "") -> None:
        """Add a user to the approved list. Must be called under self._lock."""
        approved = self._load_json(self._approved_path(platform))
        normalized_user_id = _normalize_user_id(platform, user_id)
        for approved_user_id in [
            uid for uid in approved if _user_ids_match(platform, uid, normalized_user_id)
        ]:
            del approved[approved_user_id]

        approved[normalized_user_id] = {
            "user_name": user_name,
            "approved_at": time.time(),
        }
        self._save_json(self._approved_path(platform), approved)
        # Mirror the grant into the operator's allowlist when one is configured.
        _sync_allowlist_add(platform, normalized_user_id)

    def revoke(self, platform: str, user_id: str) -> bool:
        """Remove a user from the approved list. Returns True if found."""
        path = self._approved_path(platform)
        with self._lock:
            approved = self._load_json(path)
            matching_ids = [
                uid for uid in approved if _user_ids_match(platform, uid, user_id)
            ]
            if not matching_ids:
                return False
            for approved_user_id in matching_ids:
                del approved[approved_user_id]
            self._save_json(path, approved)
            # Keep the allowlist mirror in sync (no-op if added by other means).
            _sync_allowlist_remove(platform, user_id)
            return True

    # ----- Pending codes -----

    @staticmethod
    def _hash_code(code: str, salt: bytes) -> str:
        """Hash a pairing code with the given salt using SHA-256."""
        return hashlib.sha256(salt + code.encode("utf-8")).hexdigest()

    def _finish_approval(
        self, platform: str, pending: dict, matched_key: str, matched_entry: dict
    ) -> dict:
        """Remove a pending request and approve its user. Must hold self._lock."""
        del pending[matched_key]
        self._save_json(self._pending_path(platform), pending)

        # A successful approval proves the requester is legitimate, so the
        # brute-force streak must not carry over: the counter persists in
        # _rate_limits.json and would otherwise accumulate isolated typos
        # until a single fresh typo trips a spurious lockout.
        self._reset_failed_attempts(platform)

        self._approve_user(
            platform, matched_entry["user_id"], matched_entry.get("user_name", "")
        )

        return {
            "user_id": matched_entry["user_id"],
            "user_name": matched_entry.get("user_name", ""),
        }

    def generate_code(
        self, platform: str, user_id: str, user_name: str = ""
    ) -> Optional[str]:
        """Generate a pairing code for a new user.

        Returns None if the user is rate-limited, the platform hit
        MAX_PENDING_PER_PLATFORM, or the platform is locked out. Only a salted
        SHA-256 hash of the code is persisted, never the plaintext.
        """
        with self._lock:
            self._cleanup_expired(platform)
            normalized_user_id = _normalize_user_id(platform, user_id)

            if self._is_locked_out(platform):
                return None
            if self._is_rate_limited(platform, user_id):
                return None
            pending = self._load_json(self._pending_path(platform))
            if len(pending) >= MAX_PENDING_PER_PLATFORM:
                return None

            code = "".join(secrets.choice(ALPHABET) for _ in range(CODE_LENGTH))
            salt = os.urandom(16)
            # Keyed by a random entry id, not the code itself.
            pending[secrets.token_hex(8)] = {
                "hash": self._hash_code(code, salt),
                "salt": salt.hex(),
                "user_id": normalized_user_id,
                "user_name": user_name,
                "created_at": time.time(),
            }
            self._save_json(self._pending_path(platform), pending)
            self._record_rate_limit(platform, user_id)
            return code

    def approve_code(self, platform: str, code: str) -> Optional[dict]:
        """Approve a pairing code. Adds the user to the approved list.

        Returns ``{user_id, user_name}`` on success, ``None`` if the code is
        invalid/expired OR the platform is locked out after
        ``MAX_FAILED_ATTEMPTS`` failed approvals (disambiguate with
        ``_is_locked_out``). The code is hashed with each entry's salt and
        compared in constant time; legacy plaintext-key entries are ignored
        and pruned at TTL by ``_cleanup_expired``.
        """
        with self._lock:
            self._cleanup_expired(platform)
            code = code.upper().strip()

            # Must run before the pending lookup, or an already-issued valid
            # code would still be accepted during lockout, nullifying the
            # brute-force protection.
            if self._is_locked_out(platform):
                return None

            pending = self._load_json(self._pending_path(platform))
            # Skip legacy/malformed entries rather than KeyError so an in-place
            # upgrade over an existing pending.json doesn't crash.
            for entry_id, entry in pending.items():
                if not isinstance(entry, dict) or "salt" not in entry or "hash" not in entry:
                    continue
                try:
                    salt = bytes.fromhex(entry["salt"])
                except ValueError:
                    continue
                if secrets.compare_digest(self._hash_code(code, salt), entry["hash"]):
                    return self._finish_approval(platform, pending, entry_id, entry)

            self._record_failed_attempt(platform)
            return None

    @staticmethod
    def looks_like_request_id(value: str) -> bool:
        """True when ``value`` has the shape of a ``list_pending`` request id.

        Request ids are ``secrets.token_hex(8)`` (16 hex chars); pairing codes
        are 8 chars from an uppercase alphabet, so the shapes cannot collide
        and callers accepting either can dispatch on this.
        """
        value = str(value or "").strip()
        return len(value) == 16 and all(c in "0123456789abcdefABCDEF" for c in value)

    def approve_request(self, platform: str, request_id: str) -> Optional[dict]:
        """Approve a pending request by its server-side request id.

        Grant path for authenticated admin surfaces (``hermes pairing list``,
        dashboard/desktop buttons) that must never reveal the DM'd code.
        Returns ``{user_id, user_name}`` or ``None`` for an unknown/expired id.

        Unlike :meth:`approve_code` this neither counts toward nor is gated by
        the brute-force lockout: a request id is only obtainable by an admin
        already authenticated to this store, so a stale id means "the row you
        clicked expired", not an attack -- and counting it would let a few GUI
        clicks lock the operator out of the CLI's code path.
        """
        with self._lock:
            self._cleanup_expired(platform)
            request_id = str(request_id or "").strip().lower()
            if not request_id:
                return None

            pending = self._load_json(self._pending_path(platform))
            for entry_id, entry in pending.items():
                if not isinstance(entry, dict) or "salt" not in entry or "hash" not in entry:
                    continue
                if secrets.compare_digest(str(entry_id).lower(), request_id):
                    return self._finish_approval(platform, pending, entry_id, entry)

            return None

    def list_pending(self, platform: str = None) -> list:
        """List pending pairing requests, optionally filtered by platform.

        Codes are hashed and never returned; each entry exposes a server-side
        ``request_id`` for :meth:`approve_request`. Legacy pre-hash entries
        report an empty ``request_id`` and age out at TTL.
        """
        results = []
        with self._lock:
            platforms = [platform] if platform else self._all_platforms("pending")
            for p in platforms:
                self._cleanup_expired(p)
                pending = self._load_json(self._pending_path(p))
                for entry_id, info in pending.items():
                    if not isinstance(info, dict):
                        continue
                    created_at = info.get("created_at")
                    if not isinstance(created_at, (int, float)):
                        continue
                    is_modern = isinstance(info.get("hash"), str) and isinstance(
                        info.get("salt"), str
                    )
                    results.append({
                        "platform": p,
                        "request_id": str(entry_id) if is_modern else "",
                        "user_id": info.get("user_id", ""),
                        "user_name": info.get("user_name", ""),
                        "age_minutes": int((time.time() - created_at) / 60),
                    })
        return results

    def clear_pending(self, platform: str = None) -> int:
        """Clear all pending requests. Returns count removed."""
        with self._lock:
            count = 0
            platforms = [platform] if platform else self._all_platforms("pending")
            for p in platforms:
                pending = self._load_json(self._pending_path(p))
                count += len(pending)
                self._save_json(self._pending_path(p), {})
        return count

    # ----- Rate limiting and lockout -----

    def _is_rate_limited(self, platform: str, user_id: str) -> bool:
        """Check if a user (under any alias) has requested a code too recently."""
        limits = self._load_json(self._rate_limit_path())
        return any(
            (time.time() - limits.get(f"{platform}:{alias}", 0)) < RATE_LIMIT_SECONDS
            for alias in _user_id_aliases(platform, user_id)
        )

    def _record_rate_limit(self, platform: str, user_id: str) -> None:
        """Record the time of a pairing request for rate limiting."""
        limits = self._load_json(self._rate_limit_path())
        now = time.time()
        for alias in _user_id_aliases(platform, user_id):
            limits[f"{platform}:{alias}"] = now
        self._save_json(self._rate_limit_path(), limits)

    def _is_locked_out(self, platform: str) -> bool:
        """Check if a platform is in lockout due to failed approval attempts."""
        limits = self._load_json(self._rate_limit_path())
        return time.time() < limits.get(f"_lockout:{platform}", 0)

    def _record_failed_attempt(self, platform: str) -> None:
        """Record a failed approval attempt. Triggers lockout after MAX_FAILED_ATTEMPTS."""
        limits = self._load_json(self._rate_limit_path())
        fail_key = f"_failures:{platform}"
        fails = limits.get(fail_key, 0) + 1
        limits[fail_key] = fails
        if fails >= MAX_FAILED_ATTEMPTS:
            limits[f"_lockout:{platform}"] = time.time() + LOCKOUT_SECONDS
            limits[fail_key] = 0  # Reset counter
            print(f"[pairing] Platform {platform} locked out for {LOCKOUT_SECONDS}s "
                  f"after {MAX_FAILED_ATTEMPTS} failed attempts", flush=True)
        self._save_json(self._rate_limit_path(), limits)

    def _reset_failed_attempts(self, platform: str) -> None:
        """Clear the failed-approval counter after a success (it tracks *consecutive* failures)."""
        limits = self._load_json(self._rate_limit_path())
        fail_key = f"_failures:{platform}"
        if limits.get(fail_key):
            limits[fail_key] = 0
            self._save_json(self._rate_limit_path(), limits)

    # ----- Cleanup -----

    def _cleanup_expired(self, platform: str) -> None:
        """Remove expired pending codes; malformed/legacy entries (no numeric ``created_at``) count as expired."""
        path = self._pending_path(platform)
        pending = self._load_json(path)
        now = time.time()
        expired = [
            entry_id for entry_id, info in pending.items()
            if not isinstance(info, dict)
            or not isinstance(info.get("created_at"), (int, float))
            or (now - info["created_at"]) > CODE_TTL_SECONDS
        ]
        if expired:
            for entry_id in expired:
                del pending[entry_id]
            self._save_json(path, pending)

    def _all_platforms(self, suffix: str) -> list:
        """List all platforms that have data files of a given suffix."""
        tail = f"-{suffix}.json"
        platforms = [f.name.replace(tail, "") for f in self._dir.iterdir() if f.name.endswith(tail)]
        return [p for p in platforms if not p.startswith("_")]