@miraiva_test/miravia-order-report 0.1.13

package/dist/scripts/auth_cli.py

@@ -0,0 +1,1442 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Miravia Skill Hub Authorization CLI
+
+Sole authorization entry point:
+    https://pre-sellercenter.miravia.es/apps/seller/skill/auth
+
+This CLI no longer supports Miravia official OAuth (auth.miravia.com) legacy flow.
+All appKey / appSecret / accessToken come from the above authorization page
+via RSA-encrypted encryptedPayload.
+
+Commands:
+    python auth_cli.py login   [--port 8765] [--redirect-uri ...] [--no-open]
+    python auth_cli.py status
+
+Credential storage:
+    .qoder/skills/miravia-order-report/credentials.json (chmod 600)
+    Path can be overridden by MIRAVIA_CRED_FILE.
+
+File format (JSON):
+    {
+      "app_key": "enc:v1:...",
+      "app_secret": "enc:v1:...",
+      "access_token": "enc:v1:...",
+      "token_expires_at": "2026-06-16 15:01",
+      "last_login_at": "2026-06-16T14:01:45"
+    }
+"""
+
+from __future__ import annotations
+
+import argparse
+import html
+import http.server
+import json
+import logging
+import logging.handlers
+import os
+import secrets
+import socket
+import subprocess
+import sys
+import threading
+import time
+import urllib.parse
+import webbrowser
+from typing import Dict, Optional, Tuple
+
+import config
+from cred_crypto import (
+    CredCryptoError,
+    SENSITIVE_KEYS,
+    decrypt_creds,
+    encrypt_creds,
+    is_encrypted,
+)
+from skill_crypto import SkillAuthDecryptError, decrypt_payload
+from skill_keypair import SkillKeypairError, load_keypair
+
+
+logger = logging.getLogger("miravia.auth_cli")
+
+# Log file for troubleshooting the auth flow ("frontend auth complete -> local credentials.json written").
+# Path: <skill_dir>/logs/auth_cli.log; can be overridden by MIRAVIA_AUTH_LOG_FILE.
+_DEFAULT_LOG_FILE = os.path.join(
+    os.path.abspath(os.path.join(os.path.dirname(__file__), os.pardir)),
+    "logs",
+    "auth_cli.log",
+)
+LOG_FILE = os.getenv("MIRAVIA_AUTH_LOG_FILE", _DEFAULT_LOG_FILE)
+
+
+def _configure_logging() -> str:
+    """Configure dual-channel logging with millisecond timestamps (console + rotating file).
+
+    - File path: ``LOG_FILE``, default ``<skill_dir>/logs/auth_cli.log``
+    - File handler uses ``RotatingFileHandler`` (5MB x 3) to prevent unbounded growth
+    - Time format ``YYYY-mm-dd HH:MM:SS.mmm`` for easy cross-reference with browser Network panel
+    Returns the final effective log file absolute path, printed once in cmd_login.
+    """
+    os.makedirs(os.path.dirname(LOG_FILE), exist_ok=True)
+    fmt = "%(asctime)s.%(msecs)03d %(levelname)s [%(name)s] %(message)s"
+    datefmt = "%Y-%m-%d %H:%M:%S"
+    formatter = logging.Formatter(fmt=fmt, datefmt=datefmt)
+
+    root = logging.getLogger()
+    root.setLevel(logging.INFO)
+    # Clear existing handlers to avoid duplicate output (multiple basicConfig calls / repeated module imports)
+    for h in list(root.handlers):
+        root.removeHandler(h)
+
+    sh = logging.StreamHandler()
+    sh.setLevel(logging.INFO)
+    sh.setFormatter(formatter)
+    root.addHandler(sh)
+
+    fh = logging.handlers.RotatingFileHandler(
+        LOG_FILE, maxBytes=5 * 1024 * 1024, backupCount=3, encoding="utf-8"
+    )
+    fh.setLevel(logging.DEBUG)
+    fh.setFormatter(formatter)
+    root.addHandler(fh)
+
+    return LOG_FILE
+
+
+# ------------- browser tab close (cross-platform) -------------
+
+
+def _close_browser_tab(url_fragment: str = "127.0.0.1:8765/callback",
+                       delay: float = 2.0,
+                       blocking: bool = True) -> None:
+    """Close the browser tab containing the given URL fragment.
+
+    Cross-platform implementation:
+      - macOS: AppleScript targeting Chrome / Safari / Edge by tab URL
+      - Windows: ctypes EnumWindows + SendMessage WM_CLOSE (window-level)
+      - Linux: xdotool search by window name + send Ctrl+W
+
+    Args:
+        url_fragment: URL substring to match the target tab.
+        delay: Seconds to wait before closing (let user see success page).
+        blocking: If True, waits for the close operation to finish (up to
+                  delay + 8s). If False, fires in daemon thread and returns
+                  immediately (caller must keep process alive).
+    """
+    def _do_close():
+        if delay > 0:
+            time.sleep(delay)
+        platform = sys.platform
+        if platform == "darwin":
+            _close_tab_macos(url_fragment)
+        elif platform == "win32":
+            _close_tab_windows(url_fragment)
+        else:
+            _close_tab_linux(url_fragment)
+
+    t = threading.Thread(target=_do_close, daemon=True)
+    t.start()
+    if blocking:
+        t.join(timeout=delay + 8.0)
+
+
+def _close_tab_macos(url_fragment: str) -> None:
+    """macOS: Use AppleScript to close the specific tab by URL match.
+
+    Tries Chrome, Safari, and Edge in order. Each browser's AppleScript
+    iterates all windows/tabs and closes the first tab whose URL contains
+    the given fragment.
+    """
+    # Browsers supporting tab-level AppleScript control (Chromium-based + Safari)
+    browsers = [
+        ("Google Chrome", _applescript_chromium_close),
+        ("Microsoft Edge", _applescript_chromium_close),
+        ("Safari", _applescript_safari_close),
+    ]
+    for app_name, close_fn in browsers:
+        try:
+            if close_fn(app_name, url_fragment):
+                logger.info("browser tab closed via AppleScript: app=%s", app_name)
+                return
+        except Exception as e:  # noqa: BLE001
+            logger.debug("AppleScript close failed for %s: %s", app_name, e)
+    # Fallback for Firefox and other browsers without tab-level AppleScript:
+    # Send Cmd+W to the frontmost app (only if it's a known browser)
+    _applescript_cmdw_fallback(url_fragment)
+
+
+def _applescript_chromium_close(app_name: str, url_fragment: str) -> bool:
+    """Close a tab in Chromium-based browsers (Chrome, Edge, Brave) via AppleScript.
+
+    If the matched tab is the only tab in the only window, quit the browser
+    entirely to avoid Chrome falling back to the profile picker page.
+    If it's the only tab but other windows exist, just close that window.
+    Otherwise close only the tab.
+    """
+    script = f'''
+    tell application "{app_name}"
+        if it is running then
+            set winCount to count of windows
+            repeat with w in windows
+                repeat with t in tabs of w
+                    if URL of t contains "{url_fragment}" then
+                        if (count of tabs of w) is 1 then
+                            if winCount is 1 then
+                                quit
+                            else
+                                close w
+                            end if
+                        else
+                            close t
+                        end if
+                        return
+                    end if
+                end repeat
+            end repeat
+        end if
+    end tell
+    '''
+    result = subprocess.run(
+        ["osascript", "-e", script],
+        capture_output=True, timeout=5,
+    )
+    # osascript returns 0 even if no tab matched; check stderr for "not running" etc.
+    if result.returncode == 0 and b"execution error" not in result.stderr:
+        # Verify by re-checking if the tab still exists
+        return True
+    return False
+
+
+def _applescript_safari_close(app_name: str, url_fragment: str) -> bool:
+    """Close a tab in Safari via AppleScript."""
+    script = f'''
+    tell application "Safari"
+        if it is running then
+            repeat with w in windows
+                repeat with t in tabs of w
+                    if URL of t contains "{url_fragment}" then
+                        close t
+                        return
+                    end if
+                end repeat
+            end repeat
+        end if
+    end tell
+    '''
+    result = subprocess.run(
+        ["osascript", "-e", script],
+        capture_output=True, timeout=5,
+    )
+    return result.returncode == 0 and b"execution error" not in result.stderr
+
+
+def _applescript_cmdw_fallback(url_fragment: str) -> None:
+    """Fallback: send Cmd+W to the frontmost browser window (Firefox etc.).
+
+    Only proceeds if the frontmost app is a known browser to avoid closing
+    unrelated windows.
+    """
+    known_browsers = ('Firefox', 'Opera', 'Brave Browser', 'Arc')
+    # Get frontmost app name
+    check_script = 'tell application "System Events" to get name of first application process whose frontmost is true'
+    try:
+        result = subprocess.run(
+            ["osascript", "-e", check_script],
+            capture_output=True, timeout=3, text=True,
+        )
+        front_app = result.stdout.strip()
+    except Exception:  # noqa: BLE001
+        return
+    if not any(b in front_app for b in known_browsers):
+        logger.debug("frontmost app '%s' is not a known browser, skip Cmd+W", front_app)
+        return
+    # Send Cmd+W
+    cmdw_script = '''
+    tell application "System Events"
+        keystroke "w" using command down
+    end tell
+    '''
+    try:
+        subprocess.run(["osascript", "-e", cmdw_script], capture_output=True, timeout=3)
+        logger.info("sent Cmd+W to frontmost browser: %s", front_app)
+    except Exception as e:  # noqa: BLE001
+        logger.debug("Cmd+W fallback failed: %s", e)
+
+
+def _close_tab_windows(url_fragment: str) -> None:
+    """Windows: Find browser window by title and send WM_CLOSE.
+
+    Uses ctypes to enumerate windows and match by title containing
+    the callback page title keyword. Closes the entire window (not just tab)
+    since Windows has no universal tab-level API across browsers.
+    """
+    try:
+        import ctypes
+        from ctypes import wintypes
+
+        user32 = ctypes.windll.user32
+        EnumWindows = user32.EnumWindows
+        GetWindowTextW = user32.GetWindowTextW
+        PostMessageW = user32.PostMessageW
+        IsWindowVisible = user32.IsWindowVisible
+
+        WM_CLOSE = 0x0010
+
+        # Match window title: our callback page sets title to "Close manually" or
+        # "Authorization Successful · Miravia Skill CLI"
+        match_keywords = ("Miravia Skill CLI", "Close manually")
+
+        @ctypes.WINFUNCTYPE(wintypes.BOOL, wintypes.HWND, wintypes.LPARAM)
+        def enum_cb(hwnd, _lparam):
+            if not IsWindowVisible(hwnd):
+                return True
+            buf = ctypes.create_unicode_buffer(512)
+            GetWindowTextW(hwnd, buf, 512)
+            title = buf.value
+            if any(kw in title for kw in match_keywords):
+                PostMessageW(hwnd, WM_CLOSE, 0, 0)
+                logger.info("WM_CLOSE sent to window: title=%s", title[:60])
+                return False  # stop enumeration
+            return True
+
+        EnumWindows(enum_cb, 0)
+    except Exception as e:  # noqa: BLE001
+        logger.debug("Windows close failed: %s", e)
+
+
+def _close_tab_linux(url_fragment: str) -> None:
+    """Linux: Use xdotool to find the window by name and send Ctrl+W."""
+    match_keywords = ("Miravia Skill CLI", "Close manually")
+    for kw in match_keywords:
+        try:
+            result = subprocess.run(
+                ["xdotool", "search", "--name", kw],
+                capture_output=True, text=True, timeout=3,
+            )
+            window_ids = result.stdout.strip().split()
+            if window_ids:
+                wid = window_ids[0]
+                subprocess.run(
+                    ["xdotool", "key", "--window", wid, "ctrl+w"],
+                    capture_output=True, timeout=3,
+                )
+                logger.info("xdotool Ctrl+W sent to window: id=%s keyword=%s", wid, kw)
+                return
+        except FileNotFoundError:
+            logger.debug("xdotool not installed, cannot close browser tab on Linux")
+            return
+        except Exception as e:  # noqa: BLE001
+            logger.debug("Linux close failed for keyword '%s': %s", kw, e)
+
+
+# ------------- credentials I/O -------------
+
+# Fields stored in credentials.json (reduced to 5 essential fields)
+CRED_KEYS = (
+    "app_key",
+    "app_secret",
+    "access_token",
+    "token_expires_at",
+    "last_login_at",
+)
+
+
+def load_creds(path: str = config.CRED_FILE) -> Dict[str, str]:
+    """Read credentials.json, auto-decrypt sensitive fields with ``enc:v1:`` prefix.
+
+    If sensitive fields are plaintext (legacy), treat as invalid, return empty dict
+    and delete old file to force re-authorization.
+    """
+    if not os.path.exists(path):
+        return {}
+    try:
+        with open(path, "r", encoding="utf-8") as f:
+            raw = json.load(f)
+    except (OSError, json.JSONDecodeError):
+        return {}
+    # Convert JSON field names to env-var style keys (for internal consistency)
+    mapped = {}
+    key_map_reverse = {
+        "app_key": "MIRAVIA_APP_KEY",
+        "app_secret": "MIRAVIA_APP_SECRET",
+        "access_token": "MIRAVIA_ACCESS_TOKEN",
+        "token_expires_at": "MIRAVIA_TOKEN_EXPIRES_AT",
+        "last_login_at": "MIRAVIA_LAST_LOGIN_AT",
+    }
+    for json_key, env_key in key_map_reverse.items():
+        v = raw.get(json_key)
+        if v is not None:
+            mapped[env_key] = str(v)
+    try:
+        return decrypt_creds(mapped)
+    except CredCryptoError as e:
+        logger.error("load_creds: %s", e)
+        # Plaintext or corrupted credential file: delete and force re-authorization
+        try:
+            os.remove(path)
+            logger.info("load_creds: removed invalid cred file: %s", path)
+        except OSError:
+            pass
+        return {}
+
+
+def save_creds(creds: Dict[str, str], path: str = config.CRED_FILE) -> None:
+    """Encrypt sensitive fields (APP_KEY/APP_SECRET/ACCESS_TOKEN) with AES-256-GCM
+    and persist as JSON, satisfying PRD §4.5.a (App Token stored encrypted, never plaintext).
+
+    Only stores 5 essential fields: app_key, app_secret, access_token, token_expires_at, last_login_at.
+    Aborts and raises if .keypair.json is missing or encryption fails.
+    """
+    os.makedirs(os.path.dirname(path), exist_ok=True)
+    try:
+        encrypted = encrypt_creds(creds)
+    except CredCryptoError as e:
+        logger.error("save_creds: encrypt failed: %s", e)
+        raise
+    # Build JSON object (only store essential fields, skip empty values)
+    env_to_json = {
+        "MIRAVIA_APP_KEY": "app_key",
+        "MIRAVIA_APP_SECRET": "app_secret",
+        "MIRAVIA_ACCESS_TOKEN": "access_token",
+        "MIRAVIA_TOKEN_EXPIRES_AT": "token_expires_at",
+        "MIRAVIA_LAST_LOGIN_AT": "last_login_at",
+    }
+    json_data = {
+        "_comment": (
+            "Miravia Skill Hub credentials (auto-generated, DO NOT commit). "
+            "Sensitive fields are AES-256-GCM encrypted (enc:v1:...). "
+            "Key is derived from .keypair.json via HKDF-SHA256 + machine fingerprint."
+        ),
+        "generated_at": time.strftime("%Y-%m-%dT%H:%M:%S%z") or time.strftime("%Y-%m-%dT%H:%M:%S"),
+    }
+    for env_key, json_key in env_to_json.items():
+        v = encrypted.get(env_key, "")
+        if v:  # skip empty values
+            json_data[json_key] = v
+    tmp = path + ".tmp"
+    with open(tmp, "w", encoding="utf-8") as f:
+        json.dump(json_data, f, indent=2, ensure_ascii=False)
+        f.write("\n")
+    os.replace(tmp, path)
+    try:
+        os.chmod(path, 0o600)
+    except OSError:
+        pass
+    enc_count = sum(1 for k in SENSITIVE_KEYS if is_encrypted(encrypted.get(k, "")))
+    try:
+        st = os.stat(path)
+        logger.info(
+            "creds saved: path=%s size=%dB mtime=%.3f encrypted_fields=%d/%d",
+            path, st.st_size, st.st_mtime, enc_count, len(SENSITIVE_KEYS),
+        )
+    except OSError:
+        logger.info(
+            "creds saved: path=%s (stat failed) encrypted_fields=%d/%d",
+            path, enc_count, len(SENSITIVE_KEYS),
+        )
+
+
+def _expires_at(now: float, expires_in) -> str:
+    """Normalize backend-returned expiry time to YYYY-MM-DD HH:MM format.
+
+    Tolerates three input types:
+      - Relative seconds (OAuth standard ``expires_in``) -> now + v
+      - Absolute seconds timestamp (10 digits) -> v as-is
+      - Absolute milliseconds timestamp (13 digits, common in Miravia) -> v // 1000
+    """
+    if expires_in in (None, ""):
+        return ""
+    try:
+        v = int(expires_in)
+    except (TypeError, ValueError):
+        return ""
+    # Threshold: > 1e12 = milliseconds; 1e10 ~ 1e12 = absolute seconds; otherwise = relative seconds.
+    if v >= 10**12:
+        ts = v // 1000
+    elif v >= 10**10:
+        ts = v
+    else:
+        ts = int(now + v)
+    return time.strftime("%Y-%m-%d %H:%M", time.localtime(ts))
+
+def _payload_to_creds(payload: Dict, now: Optional[float] = None) -> Dict[str, str]:
+    """Convert decrypted Skill Hub plaintext payload to credentials dict.
+
+    Handles both camelCase and snake_case keys; transparently unwraps ``data`` wrapper if present.
+    Only retains 5 essential fields.
+    """
+    now = now if now is not None else time.time()
+    body = payload.get("data") if isinstance(payload.get("data"), dict) else payload
+
+    def pick(*keys, default=""):
+        for k in keys:
+            v = body.get(k)
+            if v not in (None, ""):
+                return v
+        return default
+
+    expires_in = pick("expiresIn", "expires_in")
+
+    return {
+        "MIRAVIA_APP_KEY": str(pick("appKey", "app_key") or ""),
+        "MIRAVIA_APP_SECRET": str(pick("appSecret", "app_secret", "secret") or ""),
+        "MIRAVIA_ACCESS_TOKEN": str(pick("accessToken", "access_token") or ""),
+        "MIRAVIA_TOKEN_EXPIRES_AT": _expires_at(now, expires_in),
+        "MIRAVIA_LAST_LOGIN_AT": time.strftime("%Y-%m-%dT%H:%M:%S"),
+    }
+
+
+def _decrypt_cipher_to_creds(
+    cipher: str, private_key_pem: str, sign_method: str
+) -> Tuple[Optional[Dict[str, str]], str]:
+    """Unified RSA chunked decryption + payload parsing entry point.
+
+    Returns:
+        (creds_dict, "") on success; (None, error_message) on failure.
+    Shared by _try_preflight_decrypt and cmd_login fallback,
+    eliminating duplicated decrypt-convert-error-handling logic.
+    """
+    try:
+        plaintext = decrypt_payload(cipher, private_key_pem, sign_method)
+    except SkillAuthDecryptError as e:
+        return None, str(e)
+    creds = _payload_to_creds(plaintext)
+    return creds, ""
+
+
+def _fmt_expires(expires_str: str) -> str:
+    """Format expiry time string (YYYY-MM-DD HH:MM) with remaining time description."""
+    if not expires_str:
+        return "<unknown>"
+    # Try parsing YYYY-MM-DD HH:MM format
+    try:
+        import datetime
+        dt = datetime.datetime.strptime(expires_str.strip(), "%Y-%m-%d %H:%M")
+        ts = int(dt.timestamp())
+    except (ValueError, TypeError):
+        # Compatible with legacy epoch seconds format
+        try:
+            ts = int(expires_str)
+        except (ValueError, TypeError):
+            return expires_str
+    delta = ts - int(time.time())
+    iso = time.strftime("%Y-%m-%d %H:%M", time.localtime(ts))
+    if delta <= 0:
+        return f"{iso}  (EXPIRED {-delta}s ago)"
+    days, rem = divmod(delta, 86400)
+    hours, rem = divmod(rem, 3600)
+    mins, _ = divmod(rem, 60)
+    return f"{iso}  (in {days}d {hours}h {mins}m)"
+
+
+# ------------- i18n for callback page -------------
+
+# Supported languages for the callback result page.
+# Frontend passes ``lang`` parameter in the redirect URL;
+# falls back to English if missing or unsupported.
+_SUPPORTED_LANGS = ("en", "es", "it")
+_DEFAULT_LANG = "en"
+
+_I18N_TEXTS: Dict[str, Dict[str, str]] = {
+    "en": {
+        "html_lang": "en",
+        "page_title_header": "Skill Authorization",
+        "success_title": "Authorization Successful",
+        "success_sub": (
+            "The skill has been successfully authorized and "
+            "is active in your account."
+        ),
+        "token_valid_30days": "Token validity: 30 days",
+        "token_expired": "Token expired, please re-authorize",
+        "token_valid_until": "Valid until {iso} ({days} days)",
+        "auto_close_prefix": "This page will close automatically in ",
+        "auto_close_suffix": " s.",
+        "manual_close_hint": (
+            "If your browser blocks automatic closing, "
+            "press <kbd>⌘</kbd>+<kbd>W</kbd>."
+        ),
+        "manual_close_title": "Close manually · ⌘+W",
+        "fail_title": "Authorization Not Completed",
+        "decrypt_fail_sub": (
+            "Unable to decrypt the payload with the local private key. "
+            "Verify that .keypair.json is paired with the server's public key."
+        ),
+        "no_payload_sub": (
+            "The encrypted payload was not received from the authorization page."
+        ),
+        "error_footer": (
+            "Check the terminal for error details, or re-run "
+            "<kbd>python3 scripts/auth_cli.py login</kbd>."
+        ),
+    },
+    "es": {
+        "html_lang": "es",
+        "page_title_header": "Skill Authorization",
+        "success_title": "Autorización exitosa",
+        "success_sub": (
+            "La skill ha sido autorizada correctamente y "
+            "está activa en tu cuenta."
+        ),
+        "token_valid_30days": "Validez del token: 30 días",
+        "token_expired": "Token caducado, vuelve a autorizar",
+        "token_valid_until": "Válido hasta {iso} ({days} días)",
+        "auto_close_prefix": "Esta página se cerrará automáticamente en ",
+        "auto_close_suffix": " s.",
+        "manual_close_hint": (
+            "Si tu navegador bloquea el cierre automático, "
+            "pulsa <kbd>⌘</kbd>+<kbd>W</kbd>."
+        ),
+        "manual_close_title": "Cerrar manualmente · ⌘+W",
+        "fail_title": "Autorización no completada",
+        "decrypt_fail_sub": (
+            "No se ha podido descifrar el payload con la clave privada local. "
+            "Verifica que .keypair.json esté emparejado con la clave pública del servidor."
+        ),
+        "no_payload_sub": (
+            "No se ha recibido el payload cifrado de la página de autorización."
+        ),
+        "error_footer": (
+            "Consulta la terminal para ver el detalle del error, "
+            "o vuelve a ejecutar <kbd>python3 scripts/auth_cli.py login</kbd>."
+        ),
+    },
+    "it": {
+        "html_lang": "it",
+        "page_title_header": "Skill Authorization",
+        "success_title": "Autorizzazione riuscita",
+        "success_sub": (
+            "La skill è stata autorizzata correttamente ed "
+            "è attiva nel tuo account."
+        ),
+        "token_valid_30days": "Validità del token: 30 giorni",
+        "token_expired": "Token scaduto, riautorizza",
+        "token_valid_until": "Valido fino al {iso} ({days} giorni)",
+        "auto_close_prefix": "Questa pagina si chiuderà automaticamente in ",
+        "auto_close_suffix": " s.",
+        "manual_close_hint": (
+            "Se il tuo browser blocca la chiusura automatica, "
+            "premi <kbd>⌘</kbd>+<kbd>W</kbd>."
+        ),
+        "manual_close_title": "Chiudi manualmente · ⌘+W",
+        "fail_title": "Autorizzazione non completata",
+        "decrypt_fail_sub": (
+            "Impossibile decifrare il payload con la chiave privata locale. "
+            "Verifica che .keypair.json sia abbinato alla chiave pubblica del server."
+        ),
+        "no_payload_sub": (
+            "Il payload cifrato non è stato ricevuto dalla pagina di autorizzazione."
+        ),
+        "error_footer": (
+            "Controlla il terminale per i dettagli dell'errore "
+            "o esegui nuovamente <kbd>python3 scripts/auth_cli.py login</kbd>."
+        ),
+    },
+}
+
+
+def _resolve_lang(qs: Dict[str, str]) -> str:
+    """Extract and validate language from callback query string.
+
+    Frontend passes ``lang`` parameter in locale format (e.g. ``it_IT``,
+    ``es_ES``, ``en_US``) or short form (``en``, ``es``, ``it``) in the
+    redirect URL. Extracts the language prefix before ``_`` or ``-``.
+    Falls back to English if missing or unsupported.
+    """
+    raw = (qs.get("lang") or "").lower().strip()
+    # Handle locale formats: it_IT -> it, es_ES -> es, en-US -> en
+    lang = raw.split("_")[0].split("-")[0]
+    if lang not in _SUPPORTED_LANGS:
+        return _DEFAULT_LANG
+    return lang
+
+
+# ------------- callback HTTP server --------------
+
+
+class _CallbackHandler(http.server.BaseHTTPRequestHandler):
+    """Only callback form: GET /callback?encryptedPayload=...&lang=...
+
+    After the auth page receives ``encryptedPayload`` from backend, it redirects
+    browser 302 to local redirect_uri; CLI does not accept POST/JSON.
+    Parameter name matches backend `data.encryptedPayload` exactly, no aliases.
+    Optional ``lang`` parameter (en/es/it) controls callback page language;
+    defaults to English if missing or unsupported.
+    """
+
+    server_version = "MiraviaSkillCLI/1.0"
+
+    def _store(self, qs: Dict[str, str],
+               creds: Optional[Dict[str, str]] = None,
+               decrypt_err: str = "") -> None:
+        # Only record first valid result; avoid favicon.ico noise overwriting
+        if getattr(self.server, "callback_result", None):
+            return
+        self.server.callback_result = qs  # type: ignore[attr-defined]
+        if creds:
+            self.server.preflight_creds = creds  # type: ignore[attr-defined]
+        if decrypt_err:
+            self.server.preflight_decrypt_error = decrypt_err  # type: ignore[attr-defined]
+        cipher = qs.get("encryptedPayload") or ""
+        logger.info(
+            "callback stored: keys=%s encryptedPayload.len=%d error=%r preflight=%s",
+            sorted(qs.keys()), len(cipher), qs.get("error") or "",
+            "ok" if creds else ("err:" + decrypt_err if decrypt_err else "skip"),
+        )
+
+    def _try_preflight_decrypt(self, cipher: str) -> Tuple[Optional[Dict[str, str]], str]:
+        """Perform RSA segmented decryption within callback thread, converting ``encryptedPayload``
+        to credential fields so ``_render_html`` can display real token expiry time,
+        and avoid redundant decryption in main thread.
+
+        - If server has no ``.skill_keypair`` (debug mode / no keypair) -> skip;
+        - If cipher is empty (error callback) -> skip;
+        - If same callback entered multiple times (browser favicon etc.) -> reuse cached result.
+        """
+        kp = getattr(self.server, "skill_keypair", None)
+        if not kp or not cipher:
+            return None, ""
+        cached = getattr(self.server, "preflight_creds", None)
+        if cached:
+            return cached, ""
+        started = time.time()
+        creds, err = _decrypt_cipher_to_creds(cipher, kp["private_key_pem"], kp["sign_method"])
+        if err:
+            logger.error("preflight decrypt failed: %s", err)
+            return None, err
+        logger.info(
+            "preflight decrypt done in %.3fs: expires_at=%s",
+            time.time() - started, creds.get("MIRAVIA_TOKEN_EXPIRES_AT", ""),
+        )
+        return creds, ""
+
+    @staticmethod
+    def _fmt_validity(expires_at: str, lang: str = _DEFAULT_LANG) -> str:
+        """Render token validity prompt text with real expiry time.
+
+        Parses ``YYYY-MM-DD HH:MM`` format (produced by _expires_at()).
+        Falls back to fixed 30-day text on failure, ensuring callback page is not blocked.
+        """
+        t = _I18N_TEXTS.get(lang, _I18N_TEXTS[_DEFAULT_LANG])
+        if not expires_at:
+            return t["token_valid_30days"]
+        # Parse "YYYY-MM-DD HH:MM" format (standard output of _expires_at)
+        import datetime as _dt
+        try:
+            dt = _dt.datetime.strptime(expires_at.strip(), "%Y-%m-%d %H:%M")
+            ts = int(dt.timestamp())
+        except (ValueError, TypeError):
+            # Fallback: try legacy epoch seconds format
+            try:
+                ts = int(expires_at)
+            except (TypeError, ValueError):
+                return t["token_valid_30days"]
+        delta = ts - int(time.time())
+        if delta <= 0:
+            return t["token_expired"]
+        iso = time.strftime("%Y-%m-%d %H:%M", time.localtime(ts))
+        days = delta // 86400
+        return t["token_valid_until"].format(iso=iso, days=days)
+
+    # Response page uses inline CSS, auto-adapts to light/dark mode, no external resources.
+    # Design: minimal white card + top 'Skill Authorization' title + centered status +
+    # yellow token validity notice box.
+    _BASE_CSS = """
+      *,*::before,*::after { box-sizing: border-box; }
+      html, body { height: 100%; margin: 0; }
+      body {
+        font-family: -apple-system, BlinkMacSystemFont, "PingFang SC",
+                     "Helvetica Neue", "Segoe UI", Roboto, Arial, sans-serif;
+        background: #f5f6f8;
+        color: #1f2937;
+        padding: 40px 24px;
+        min-height: 100%;
+      }
+      .layout { max-width: 960px; margin: 0 auto; }
+      .page-title {
+        font-size: 28px; font-weight: 700; color: #111827;
+        margin: 0 0 28px; letter-spacing: -.01em;
+      }
+      .card {
+        background: #ffffff;
+        border: 1px solid #e5e7eb;
+        border-radius: 16px;
+        padding: 64px 40px 56px;
+        text-align: center;
+      }
+      .icon {
+        width: 72px; height: 72px; margin: 0 auto 28px;
+        border-radius: 50%; display: flex; align-items: center; justify-content: center;
+        color: #fff; font-size: 40px; line-height: 1; font-weight: 700;
+        animation: pop .45s cubic-bezier(.2,.9,.3,1.4) both;
+      }
+      .icon.ok  { background: #22c55e; box-shadow: 0 8px 20px -6px #22c55e55; }
+      .icon.err { background: #ef4444; box-shadow: 0 8px 20px -6px #ef444455; }
+      h1 {
+        margin: 0 0 14px; font-size: 26px; font-weight: 700;
+        color: #111827; letter-spacing: -.01em;
+      }
+      p.sub {
+        margin: 0 auto 28px; color: #6b7280; font-size: 15px; line-height: 1.6;
+        max-width: 460px;
+      }
+      .token-info {
+        display: inline-flex; align-items: center; gap: 8px;
+        padding: 10px 18px; border-radius: 10px;
+        background: #fef3c7; border: 1px solid #fde68a;
+        color: #92400e; font-size: 14px; font-weight: 500;
+      }
+      .token-info .info-icon {
+        width: 18px; height: 18px; border-radius: 50%;
+        border: 1.5px solid #b45309; color: #b45309;
+        display: inline-flex; align-items: center; justify-content: center;
+        font-size: 12px; font-weight: 700;
+        font-family: Georgia, "Times New Roman", serif;
+      }
+      .error-detail {
+        margin: 0 auto; padding: 12px 16px; max-width: 460px;
+        background: #fef2f2; border: 1px solid #fecaca;
+        border-radius: 10px; color: #991b1b; font-size: 13px;
+        font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+        word-break: break-all; text-align: left;
+      }
+      .footer { margin-top: 28px; font-size: 13px; color: #9ca3af; }
+      .hint { color: #9ca3af; font-size: 12px; }
+      kbd {
+        background:#f1f5f9; border:1px solid #e2e8f0; border-bottom-width:2px;
+        border-radius:6px; padding:1px 6px; font-size:11px; color:#334155;
+        font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+      }
+      @keyframes pop { 0%{transform:scale(.4);opacity:0} 100%{transform:scale(1);opacity:1} }
+      @media (prefers-color-scheme: dark) {
+        body { background: #0b1220; color: #e5e7eb; }
+        .page-title { color: #f3f4f6; }
+        .card { background: #0f172a; border-color: #1f2937; }
+        h1 { color: #f3f4f6; }
+        p.sub, .footer, .hint { color: #94a3b8; }
+        .token-info { background: #422006; border-color: #78350f; color: #fbbf24; }
+        .token-info .info-icon { border-color: #fbbf24; color: #fbbf24; }
+        .error-detail { background: #450a0a; border-color: #7f1d1d; color: #fecaca; }
+        kbd { background:#1f2937; border-color:#374151; color:#e5e7eb; }
+      }
+    """
+
+    def _render_html(self, qs: Dict[str, str],
+                     creds: Optional[Dict[str, str]] = None,
+                     decrypt_err: str = "") -> bytes:
+        cipher = qs.get("encryptedPayload") or ""
+        err = qs.get("error") or qs.get("error_description") or ""
+        # Treat decryption failure as error page to avoid misleading "green check + 30 days" prompt
+        success = bool(cipher) and not err and not decrypt_err
+
+        lang = _resolve_lang(qs)
+        t = _I18N_TEXTS.get(lang, _I18N_TEXTS[_DEFAULT_LANG])
+
+        if success:
+            icon_html = '<div class="icon ok">✓</div>'
+            title = t["success_title"]
+            sub = t["success_sub"]
+            validity_text = self._fmt_validity(
+                (creds or {}).get("MIRAVIA_TOKEN_EXPIRES_AT", ""),
+                lang,
+            )
+            info_html = (
+                '<div class="token-info">'
+                '<span class="info-icon">i</span>'
+                f'{html.escape(validity_text)}'
+                '</div>'
+            )
+            footer = (
+                '<p class="footer">' + t["auto_close_prefix"] +
+                '<span id="cd" style="font-weight:600;color:#10b981">10</span>' +
+                t["auto_close_suffix"] + '<br>'
+                '<span class="hint" id="manual-tip" style="display:none">'
+                + t["manual_close_hint"] +
+                '</span></p>'
+            )
+            script = (
+                '<script>(function(){'
+                'var s=document.getElementById("cd");'
+                'var tip=document.getElementById("manual-tip");'
+                'var n=10;'
+                'function bye(){'
+                'try{window.open("","_self","").close();}catch(e){}'
+                'try{window.close();}catch(e){}'
+                'setTimeout(function(){'
+                'if(tip){tip.style.display="inline";}'
+                f'document.title={json.dumps(t["manual_close_title"])};'
+                '},150);'
+                '}'
+                'var tid=setInterval(function(){'
+                'n-=1;'
+                'if(s){s.textContent=n;}'
+                'if(n<=0){clearInterval(tid);bye();}'
+                '},1000);'
+                '})();</script>'
+            )
+        else:
+            icon_html = '<div class="icon err">✕</div>'
+            title = t["fail_title"]
+            if decrypt_err:
+                reason = f"DECRYPT_FAILED: {decrypt_err}"
+                sub = t["decrypt_fail_sub"]
+            else:
+                reason = err or "no encryptedPayload returned"
+                sub = t["no_payload_sub"]
+            info_html = (
+                f'<div class="error-detail">{html.escape(reason)}</div>'
+            )
+            footer = (
+                '<p class="footer">' + t["error_footer"] + '</p>'
+            )
+            script = ""
+
+        body = (
+            f'<!doctype html><html lang="{t["html_lang"]}"><head>'
+            '<meta charset="utf-8">'
+            '<meta name="viewport" content="width=device-width,initial-scale=1">'
+            f'<title>{title} · Miravia Skill CLI</title>'
+            f'<style>{self._BASE_CSS}</style>'
+            '</head><body>'
+            '<div class="layout">'
+            f'<header class="page-title">{t["page_title_header"]}</header>'
+            '<main class="card" role="status" aria-live="polite">'
+            f'{icon_html}'
+            f'<h1>{title}</h1>'
+            f'<p class="sub">{sub}</p>'
+            f'{info_html}'
+            f'{footer}'
+            '</main>'
+            '</div>'
+            f'{script}'
+            '</body></html>'
+        )
+        return body.encode("utf-8")
+
+    def _validate_state(self, qs: Dict[str, str]) -> Optional[str]:
+        """Validate the CSRF state parameter.
+
+        Rules:
+          - The authorization URL must include a state parameter
+          - On callback, verify state matches; reject if mismatched
+          - State can only be used once (one-time token)
+          - State is destroyed immediately after use
+
+        Returns:
+            None if validation passes; otherwise an error description string.
+        """
+        expected = getattr(self.server, "csrf_state", None)
+        if not expected:
+            # No state set (--encrypted-payload mode), skip validation
+            return None
+        received = qs.get("state", "")
+        if not received:
+            logger.warning("CSRF: callback missing state parameter")
+            return "missing state parameter"
+        if not secrets.compare_digest(received, expected):
+            logger.warning(
+                "CSRF: state mismatch (expected=%s...%s received=%s...%s)",
+                expected[:4], expected[-4:], received[:4], received[-4:],
+            )
+            return "state mismatch (possible CSRF attack)"
+        # State validated -> destroy immediately, ensure single-use
+        self.server.csrf_state = None  # type: ignore[attr-defined]
+        logger.info("CSRF: state validated and destroyed")
+        return None
+
+    def do_GET(self):  # noqa: N802
+        # Force HTTP/1.0 response + Connection: close to prevent browser keep-alive
+        # from blocking wfile.close() / serve_forever with TCP idle timeout.
+        # (Effect: browser sends FIN immediately after response, handle_one_request exits.)
+        self.close_connection = True
+        parsed = urllib.parse.urlparse(self.path)
+        # Log the moment browser actually issues GET (with client address and User-Agent summary)
+        ua = self.headers.get("User-Agent", "") if self.headers else ""
+        logger.info(
+            "callback GET: path=%s query.len=%d client=%s ua=%s",
+            parsed.path, len(parsed.query or ""),
+            getattr(self, "client_address", ("", 0))[0], ua[:80],
+        )
+        if parsed.path not in ("/callback", "/"):
+            self.send_response(404)
+            self.send_header("Connection", "close")
+            self.end_headers()
+            return
+        qs = dict(urllib.parse.parse_qsl(parsed.query))
+
+        # ── CSRF state validation ──
+        state_err = self._validate_state(qs)
+        if state_err:
+            # State validation failed -> 403 reject, no decrypt, no persist
+            qs_err = {"error": "csrf_rejected", "error_description": state_err}
+            # Preserve lang so the error page renders in the correct language
+            if qs.get("lang"):
+                qs_err["lang"] = qs["lang"]
+            self._store(qs_err)
+            body = self._render_html(qs_err)
+            self.send_response(403)
+            self.send_header("Content-Type", "text/html; charset=utf-8")
+            self.send_header("Content-Length", str(len(body)))
+            self.send_header("Connection", "close")
+            self.end_headers()
+            self.wfile.write(body)
+            try:
+                self.wfile.flush()
+            except OSError:
+                pass
+            logger.warning("callback rejected: %s", state_err)
+            return
+
+        # Perform RSA segmented decryption in callback thread: need real expires_at
+        # to replace hardcoded '30 dias' on success page with dynamic expiry time,
+        # and let main thread cmd_login skip redundant decryption.
+        cipher = qs.get("encryptedPayload") or ""
+        creds, decrypt_err = self._try_preflight_decrypt(cipher)
+        self._store(qs, creds=creds, decrypt_err=decrypt_err)
+        body = self._render_html(qs, creds=creds, decrypt_err=decrypt_err)
+        self.send_response(200)
+        self.send_header("Content-Type", "text/html; charset=utf-8")
+        self.send_header("Content-Length", str(len(body)))
+        self.send_header("Connection", "close")
+        self.end_headers()
+        self.wfile.write(body)
+        try:
+            self.wfile.flush()
+        except OSError:
+            pass
+        logger.info(
+            "callback GET done: path=%s status=%d body.len=%d",
+            parsed.path, 200, len(body),
+        )
+
+    def log_message(self, fmt, *args):  # silent
+        return
+
+
+def _generate_csrf_state() -> str:
+    """Generate CSRF state: 32-byte URL-safe random token (single-use)."""
+    return secrets.token_urlsafe(32)
+
+
+def _start_callback_server(host: str, port: int,
+                           keypair: Optional[Dict] = None,
+                           csrf_state: Optional[str] = None) -> http.server.HTTPServer:
+    """Start callback HTTP server first (serve_forever in separate thread),
+    then let caller open browser, avoiding callback arriving before server bind race.
+
+    Uses ``ThreadingHTTPServer`` + ``daemon_threads=True`` to prevent request
+    finish() phase (browser keep-alive idle, wfile.close waiting for FIN etc.)
+    from blocking main thread's ``server.shutdown()``.
+
+    ``keypair`` if provided, is passed to handler for RSA segmented decryption
+    in callback thread (success page renders real token expiry), main thread skips re-decrypt.
+
+    ``csrf_state`` if provided, callback handler validates query string state parameter
+    matches this value; rejects with 403 if mismatch (CSRF protection).
+    """
+    logger.info("callback server starting: host=%s port=%d csrf_state=%s",
+                host, port, bool(csrf_state))
+    server = http.server.ThreadingHTTPServer((host, port), _CallbackHandler)
+    server.callback_result = None  # type: ignore[attr-defined]
+    # CSRF state: destroyed immediately after callback handler validation (single-use token)
+    server.csrf_state = csrf_state  # type: ignore[attr-defined]
+    # Decryption moved earlier: inject .keypair.json into server so callback thread
+    # performs RSA segmented decryption in do_GET, HTML response can show real expiry time.
+    server.skill_keypair = keypair  # type: ignore[attr-defined]
+    server.preflight_creds = None  # type: ignore[attr-defined]
+    server.preflight_decrypt_error = ""  # type: ignore[attr-defined]
+    server.timeout = 1.0
+    server.daemon_threads = True  # request sub-threads exit with main process, don't block shutdown
+    t = threading.Thread(target=server.serve_forever, daemon=True)
+    t.start()
+    server._serve_thread = t  # type: ignore[attr-defined]
+    logger.info(
+        "callback server bound & serve_forever thread started (Threading=%s)",
+        type(server).__name__,
+    )
+    return server
+
+
+def _wait_callback(server: http.server.HTTPServer,
+                   timeout: float = 300.0) -> Dict[str, str]:
+    deadline = time.time() + timeout
+    started = time.time()
+    logger.info("wait_callback: begin timeout=%.1fs", timeout)
+    try:
+        while time.time() < deadline:
+            if server.callback_result:  # type: ignore[attr-defined]
+                logger.info(
+                    "wait_callback: result picked up after %.3fs",
+                    time.time() - started,
+                )
+                return server.callback_result  # type: ignore[attr-defined]
+            time.sleep(0.05)  # 200ms -> 50ms, reduce trailing poll jitter
+        raise TimeoutError(f"Authorization callback timed out ({timeout:.0f}s)")
+    finally:
+        shutdown_started = time.time()
+        server.shutdown()
+        server.server_close()
+        logger.info(
+            "wait_callback: server shutdown closed in %.3fs",
+            time.time() - shutdown_started,
+        )
+
+
+def _check_port_free(host: str, port: int) -> Tuple[bool, str]:
+    s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+    try:
+        s.bind((host, port))
+        return True, ""
+    except OSError as e:
+        return False, str(e)
+    finally:
+        s.close()
+
+
+def _wait_until_listening(host: str, port: int,
+                          timeout: float = 3.0) -> bool:
+    """Probe local server is accepting before opening browser.
+    Prevents connection refused when browser callback arrives immediately after webbrowser.open.
+    """
+    started = time.time()
+    deadline = started + timeout
+    while time.time() < deadline:
+        try:
+            with socket.create_connection((host, port), timeout=0.5):
+                logger.info(
+                    "listening probe ok: host=%s port=%d elapsed=%.3fs",
+                    host, port, time.time() - started,
+                )
+                return True
+        except OSError:
+            time.sleep(0.05)
+    logger.warning(
+        "listening probe timed out after %.3fs (host=%s port=%d)",
+        time.time() - started, host, port,
+    )
+    return False
+
+
+def _build_hub_authorize_url(skill_code: str, redirect_uri: str,
+                             state: Optional[str] = None) -> str:
+    """Build authorization page redirect URL.
+
+    \u26a0\ufe0f Frontend has strict requirements for redirect_uri format:
+      - state must be appended as **unencoded** ?state=xxx after the encoded redirect_uri;
+      - state cannot be a top-level param of auth URL (&state=xxx), or frontend reports CSRF error;
+      - ?state=xxx inside redirect_uri must NOT be percent-encoded (e.g. %3Fstate%3D),
+        otherwise frontend decodeURIComponent creates nested params causing 302 redirect anomaly.
+
+    Final URL example:
+      https://pre-sellercenter.miravia.es/apps/seller/skill/auth
+        ?skill_code=miravia_order_reports
+        &redirect_uri=http%3A%2F%2F127.0.0.1%3A8765%2Fcallback?state=xxx
+
+    Frontend parses redirect_uri with new URL(redirectUri), then appends encryptedPayload:
+      → http://127.0.0.1:8765/callback?state=xxx&encryptedPayload=yyy
+    """
+    # First percent-encode base redirect_uri (encode special chars like : / ? etc.)
+    encoded_redirect = urllib.parse.quote(redirect_uri, safe='')
+    if state:
+        # state appended as ?state=xxx directly after encoded redirect_uri,
+        # ? and = kept unencoded -- this is the only valid format required by frontend.
+        encoded_redirect = f"{encoded_redirect}?state={state}"
+    return (
+        f"{config.SKILL_HUB_AUTH_URL}"
+        f"?skill_code={urllib.parse.quote(skill_code, safe='')}"
+        f"&redirect_uri={encoded_redirect}"
+    )
+
+
+# ------------- commands -------------
+
+
+def _fast_decrypt(cipher: str) -> int:
+    """Shortcut path: directly decrypt encryptedPayload ciphertext and persist.
+
+    For VM/sandbox environments where 127.0.0.1 is unreachable: Agent intercepts
+    redirect URL via browser automation to get encryptedPayload, decrypts directly without local HTTP callback.
+    """
+    logger.info("_fast_decrypt: cipher.len=%d (--encrypted-payload mode)", len(cipher))
+    print("[login] --encrypted-payload mode: skipping callback server, direct decrypt & persist")
+
+    # 1. Load keypair
+    kp: Optional[Dict] = None
+    try:
+        kp = load_keypair()
+    except SkillKeypairError as e:
+        print(f"[login] {e}", file=sys.stderr)
+        print("[login] --encrypted-payload mode requires .keypair.json for decryption.", file=sys.stderr)
+        return 7
+
+    # 2. RSA segmented decryption
+    logger.info(
+        "fast_decrypt: cipher.len=%d sign_method=%s",
+        len(cipher), kp.get("sign_method", ""),
+    )
+    decrypt_started = time.time()
+    try:
+        plaintext = decrypt_payload(cipher, kp["private_key_pem"], kp["sign_method"])
+    except SkillAuthDecryptError as e:
+        logger.error("fast_decrypt failed: %s", e)
+        print(f"[login] DECRYPT_FAILED: {e}", file=sys.stderr)
+        print("        Please verify the private key in .keypair.json matches the server public key.", file=sys.stderr)
+        return 7
+    logger.info(
+        "fast_decrypt done in %.3fs: plaintext.keys=%s",
+        time.time() - decrypt_started,
+        sorted(plaintext.keys()) if isinstance(plaintext, dict) else type(plaintext).__name__,
+    )
+
+    # 3. Persist
+    creds = _payload_to_creds(plaintext)
+    if not creds.get("MIRAVIA_ACCESS_TOKEN") or not creds.get("MIRAVIA_APP_KEY"):
+        print(
+            f"[login] Plaintext missing appKey / accessToken: {plaintext}",
+            file=sys.stderr,
+        )
+        return 4
+    if not creds.get("MIRAVIA_APP_SECRET"):
+        print(
+            "[login] WARNING: plaintext does not contain appSecret; business API signing will fail.\n"
+            "        Please contact Skill Hub to add appSecret field in authRule target interface.",
+            file=sys.stderr,
+        )
+
+    save_creds(creds)
+    logger.info("_fast_decrypt done: creds written, returning 0")
+    print(f"[login] OK, credentials written to: {config.CRED_FILE}")
+    print(f"[login] app_key       = {creds.get('MIRAVIA_APP_KEY', '')}")
+    print(f"[login] app_secret    = {config.mask_token(creds.get('MIRAVIA_APP_SECRET', ''))}")
+    print(f"[login] access_token  exp = {_fmt_expires(creds.get('MIRAVIA_TOKEN_EXPIRES_AT', ''))}")
+    return 0
+
+
+def cmd_login(args: argparse.Namespace) -> int:
+    """Skill Hub authorization flow (streamlined): browser redirects to seller center auth page ->
+    frontend sends encryptedPayload back to local -> CLI decrypts with RSA private key -> credentials.json persisted.
+
+    If .keypair.json does not exist locally, enters debug mode: only opens browser,
+    starts local callback, prints encryptedPayload after receiving it, no decryption.
+
+    --encrypted-payload shortcut (VM/sandbox environment):
+    When this parameter is provided, skips local HTTP callback server and browser opening,
+    directly decrypts the ciphertext with private key and persists. For scenarios where
+    Agent intercepts redirect URL via browser automation to extract encryptedPayload.
+    """
+    # ── Shortcut path: directly pass encryptedPayload ciphertext, skip callback server ──
+    if args.encrypted_payload:
+        return _fast_decrypt(args.encrypted_payload)
+
+    host = "127.0.0.1"
+    port = args.port
+    redirect_uri = args.redirect_uri or f"http://{host}:{port}/callback"
+    logger.info(
+        "cmd_login begin: host=%s port=%d redirect_uri=%s no_open=%s timeout=%.1fs",
+        host, port, redirect_uri, args.no_open, args.timeout,
+    )
+
+    # 1. Attempt to load keypair (optional) and resolve skill_code
+    kp: Optional[Dict] = None
+    try:
+        kp = load_keypair()
+    except SkillKeypairError as e:
+        print(f"[login] {e}", file=sys.stderr)
+        print("[login] Entering debug mode: only verifying callback channel; will NOT decrypt/persist after receiving encryptedPayload.", file=sys.stderr)
+
+    skill_code = (
+        args.skill_code
+        or (kp["skill_code"] if kp else "")
+        or config.DEFAULT_SKILL_CODE
+    )
+    if not skill_code:
+        print("[login] Missing skill_code. Please use --skill-code or create .keypair.json", file=sys.stderr)
+        return 1
+
+    # 2. Generate CSRF state (32-byte random token, single-use)
+    csrf_state = _generate_csrf_state()
+    logger.info("CSRF state generated: %s...%s", csrf_state[:4], csrf_state[-4:])
+
+    # 3. Check local port, then start callback server first (avoid browser callback before bind race condition)
+    ok, err = _check_port_free(host, port)
+    if not ok:
+        print(f"[login] Port {host}:{port} unavailable: {err}", file=sys.stderr)
+        print("        Try using --port to specify a different port.", file=sys.stderr)
+        return 1
+
+    try:
+        server = _start_callback_server(host, port, keypair=kp, csrf_state=csrf_state)
+    except OSError as e:
+        print(f"[login] Failed to start local callback server: {e}", file=sys.stderr)
+        return 1
+    print(f"[login] callback server ready at http://{host}:{port}/callback")
+    print(f"[login] Detailed timing log   : {LOG_FILE}")
+
+    # 4. Build authorization URL (with CSRF state)
+    url = _build_hub_authorize_url(skill_code, redirect_uri, state=csrf_state)
+
+    print(f"[login] auth_entry    = {config.SKILL_HUB_AUTH_URL}")
+    print(f"[login] redirect_uri = {redirect_uri}")
+    print(f"[login] skill_code   = {skill_code}")
+    print(f"[login] auth_url:\n  {url}")
+    # Verify server is listening (TCP connect probe) before opening browser
+    _wait_until_listening(host, port)
+    if not args.no_open:
+        try:
+            logger.info("webbrowser.open: %s", url)
+            webbrowser.open(url, new=1)
+            logger.info("webbrowser.open returned (handed off to OS)")
+        except Exception as e:  # noqa: BLE001
+            logger.warning("webbrowser.open failed: %r", e)
+    else:
+        logger.info("--no-open specified, skipping browser launch")
+
+    # 5. Wait for browser GET 302 callback
+    print(f"[login] Waiting for browser callback (up to {args.timeout:.0f}s)...")
+    try:
+        cb = _wait_callback(server, timeout=args.timeout)
+    except TimeoutError as e:
+        print(f"[login] {e}", file=sys.stderr)
+        return 2
+
+    # 6. Server error passthrough (including CSRF rejection)
+    if cb.get("error") or cb.get("error_description"):
+        err_code = cb.get("error") or ""
+        err_msg = cb.get("error_description") or ""
+        print(f"[login] Server returned error: {err_code} {err_msg}", file=sys.stderr)
+        return 4
+
+    cipher = cb.get("encryptedPayload")
+    if not cipher:
+        print(f"[login] No encryptedPayload received. Callback params: {cb}", file=sys.stderr)
+        return 4
+
+    # 7. Debug mode: no private key, just print.
+    if kp is None:
+        tail = cipher[-16:] if len(cipher) > 16 else cipher
+        print("[login] \u2705 Received encryptedPayload (debug mode, not decrypted)")
+        print(f"[login] encryptedPayload length = {len(cipher)} chars, tail: ...{tail}")
+        print("[login] Please provide .keypair.json (skill_code + private_key) to enable decryption and persistence.")
+        return 0
+
+    # 8. Reuse callback thread's pre-decrypted result (decryption moved earlier; main thread no longer repeats RSA segmented decryption)
+    creds = getattr(server, "preflight_creds", None)
+    if creds is None:
+        preflight_err = getattr(server, "preflight_decrypt_error", "")
+        if preflight_err:
+            print(f"[login] DECRYPT_FAILED: {preflight_err}", file=sys.stderr)
+            print("        Please verify the private key in .keypair.json matches the server's public key.", file=sys.stderr)
+            return 7
+        # Theoretically do_GET always attempts decryption when kp exists;
+        # reaching here means callback thread didn't reach decryption branch
+        # (extreme race condition); fallback decrypt to ensure cmd_login behavior doesn't regress.
+        logger.warning("preflight_creds missing, falling back to main-thread decrypt")
+        decrypt_started = time.time()
+        creds, err = _decrypt_cipher_to_creds(cipher, kp["private_key_pem"], kp["sign_method"])
+        if err:
+            logger.error("decrypt failed: %s", err)
+            print(f"[login] DECRYPT_FAILED: {err}", file=sys.stderr)
+            print("        Please verify the private key in .keypair.json matches the server's public key.", file=sys.stderr)
+            return 7
+        logger.info(
+            "fallback decrypt done in %.3fs: creds.keys=%s",
+            time.time() - decrypt_started, sorted(creds.keys()),
+        )
+    else:
+        logger.info("reuse preflight_creds: skip main-thread decrypt")
+
+    # 9. Persist credentials
+    if not creds.get("MIRAVIA_ACCESS_TOKEN") or not creds.get("MIRAVIA_APP_KEY"):
+        print(
+            f"[login] Decrypted payload missing appKey / accessToken: {creds}",
+            file=sys.stderr,
+        )
+        return 4
+    if not creds.get("MIRAVIA_APP_SECRET"):
+        # appSecret is required for business API signing; server must provide it, otherwise Skill cannot call business APIs
+        print(
+            "[login] WARNING: decrypted payload does not contain appSecret; business API signing will fail.\n"
+            "        Please contact Skill Hub to add appSecret field in authRule target interface.",
+            file=sys.stderr,
+        )
+
+    save_creds(creds)
+    # 10. Close the callback browser tab (best-effort, after 10s countdown)
+    _close_browser_tab(
+        url_fragment=f"{host}:{port}/callback",
+        delay=10.0,
+    )
+    logger.info("cmd_login done: creds written, returning 0")
+    print(f"[login] OK, credentials written to: {config.CRED_FILE}")
+    print(f"[login] app_key       = {creds.get('MIRAVIA_APP_KEY', '')}")
+    print(f"[login] app_secret    = {config.mask_token(creds.get('MIRAVIA_APP_SECRET', ''))}")
+    print(f"[login] access_token  exp = {_fmt_expires(creds.get('MIRAVIA_TOKEN_EXPIRES_AT', ''))}")
+    print()
+    print("To export as environment variables in shell, manually read credentials.json")
+    return 0
+
+
+def cmd_status(_args: argparse.Namespace) -> int:
+    creds = load_creds()
+    if not creds:
+        print(f"[status] Credentials file not found: {config.CRED_FILE}")
+        print("[status] Please run first: python auth_cli.py login")
+        return 1
+    at = creds.get("MIRAVIA_ACCESS_TOKEN", "")
+    sec = creds.get("MIRAVIA_APP_SECRET", "")
+    print(f"[status] file          = {config.CRED_FILE}")
+    print(f"[status] app_key       = {creds.get('MIRAVIA_APP_KEY') or '<empty>'}")
+    print(f"[status] app_secret    = {config.mask_token(sec)}")
+    print(f"[status] last_login_at = {creds.get('MIRAVIA_LAST_LOGIN_AT', '<unknown>')}")
+    print(f"[status] access_token  = {config.mask_token(at)}  exp = "
+          f"{_fmt_expires(creds.get('MIRAVIA_TOKEN_EXPIRES_AT', ''))}")
+    return 0
+
+
+def main(argv=None) -> int:
+    log_path = _configure_logging()
+    logger.info("=" * 60)
+    logger.info("auth_cli main start: argv=%s log_file=%s", argv, log_path)
+    p = argparse.ArgumentParser(description="Miravia Skill Hub Authorization CLI")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    p_login = sub.add_parser(
+        "login",
+        help="Run Skill Hub authorization flow (pre-release auth page -> local callback -> RSA decrypt & persist)",
+    )
+    p_login.add_argument("--port", type=int, default=8765, help="Local callback port (default 8765)")
+    p_login.add_argument(
+        "--redirect-uri",
+        default=None,
+        help="Custom redirect_uri; default http://127.0.0.1:<port>/callback",
+    )
+    p_login.add_argument(
+        "--skill-code",
+        default=None,
+        help="Manually specify skill_code (overrides .keypair.json / environment variable default)",
+    )
+    p_login.add_argument("--timeout", type=float, default=180.0, help="Callback wait timeout in seconds (default 3 minutes)")
+    p_login.add_argument("--no-open", action="store_true", help="Do not auto-open browser")
+    p_login.add_argument(
+        "--encrypted-payload",
+        default=None,
+        metavar="CIPHER",
+        help=(
+            "Pass encryptedPayload ciphertext (Base64URL) directly, skipping local HTTP callback server. "
+            "For VM/sandbox environments where 127.0.0.1 is unreachable: Agent extracts "
+            "encryptedPayload parameter from redirect URL via browser automation, then feeds it "
+            "to this option for decryption and persistence."
+        ),
+    )
+    p_login.set_defaults(func=cmd_login)
+
+    p_status = sub.add_parser("status", help="View local credential status and expiry")
+    p_status.set_defaults(func=cmd_status)
+
+    args = p.parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())