aukeys-opscli 0.0.6__py3-none-any.whl

opscli/auth/cli.py

@@ -0,0 +1,255 @@
+"""auth 子命令 CLI 层。
+
+提供认证授权相关的所有 CLI 命令，包括：
+- 授权管理：login（Device Flow 登录）、logout（清除凭证）、doctor（环境诊断）
+- Token 操作：status（查看状态）、get（获取 JWT）、check（检测有效性）、refresh（刷新）
+- 系统管理：list（列出系统）、sync（从 ops 同步）、add/remove（手动管理）
+"""
+import sys
+import base64
+import json as _json
+import webbrowser
+import typer
+import httpx
+from rich.console import Console
+from rich.table import Table
+from opscli.auth import AuthClient, BUILTIN_SYSTEMS, OPS_URL
+from opscli.auth.storage.credential_store import CredentialStore
+from opscli.auth.core.system_registry import SystemRegistry
+from opscli.auth.core.device_flow import DeviceFlow
+from opscli.auth.exceptions import (
+    NotAuthenticatedError,
+    SystemNotFoundError,
+    DeviceFlowExpiredError,
+    DeviceFlowDeniedError,
+)
+
+app = typer.Typer(help="认证授权管理")
+token_app = typer.Typer(help="JWT Token 管理")
+system_app = typer.Typer(help="系统注册管理")
+app.add_typer(token_app, name="token")
+app.add_typer(system_app, name="system")
+
+console = Console()
+
+
+def _display_scope(jwt: str, system: str):
+    """解析 JWT payload 展示已授权权限范围。
+
+    JWT 格式为 header.payload.signature，此处仅解码 payload 部分。
+    Base64 URL 安全编码需要补齐 padding（=）才能正确解码。
+    """
+    try:
+        parts = jwt.split(".")
+        if len(parts) < 2:
+            return
+        # Base64 URL 安全编码可能缺少 padding，按 4 的倍数补齐
+        padding = "=" * (-len(parts[1]) % 4)
+        payload = _json.loads(base64.urlsafe_b64decode(parts[1] + padding))
+        scope = payload.get("scope", "")
+        if scope:
+            scopes = scope.split()
+            console.print(f"    [dim]权限（{len(scopes)} 项）：{', '.join(scopes)}[/dim]")
+    except Exception:
+        pass
+
+
+def _client() -> AuthClient:
+    """创建默认配置的 AuthClient 实例。"""
+    return AuthClient()
+
+
+def _registry() -> SystemRegistry:
+    """创建包含内置系统的 SystemRegistry 实例。"""
+    return SystemRegistry(builtin_systems=BUILTIN_SYSTEMS)
+
+
+# ── 授权管理 ──────────────────────────────────────────
+
+@app.command()
+def login():
+    """发起 Device Flow 授权（自动打开浏览器）。"""
+    store = CredentialStore()
+    flow = DeviceFlow(ops_url=OPS_URL, store=store)
+    try:
+        code = flow.request_device_code()
+        console.print(f"\n[bold]请在浏览器打开：[/bold] {code['verification_url']}")
+        console.print(f"[bold]输入验证码：  [/bold] [green]{code['user_code']}[/green]")
+        console.print(f"等待授权中...（{code['expires_in']} 秒内完成）\n")
+        webbrowser.open(f"{code['verification_url']}?code={code['user_code']}")
+        result = flow.poll(code["device_code"], interval=code.get("interval", 3))
+        # 登录成功后自动同步系统列表，免去用户手动运行 opscli auth system sync
+        try:
+            client = _client()
+            resp = httpx.get(
+                f"{OPS_URL}/v1/cli/systems",
+                headers=client.build_session_headers("ops"),
+                timeout=10,
+            )
+            if resp.status_code == 200:
+                _registry().sync_from_ops(resp.json().get("systems", []))
+        except Exception:
+            pass
+        console.print(f"[green]✓ 授权成功！账号：{result.get('email', '')}[/green]")
+    except (DeviceFlowExpiredError, DeviceFlowDeniedError) as e:
+        console.print(f"[red]✗ {e}[/red]")
+        raise typer.Exit(1)
+
+
+@app.command()
+def logout():
+    """清除本地所有凭证"""
+    CredentialStore().clear()
+    console.print("[green]✓ 已退出，本地凭证已清除[/green]")
+
+
+@token_app.command("status")
+def status():
+    """查看当前登录状态与各系统 Token 情况"""
+    c = _client()
+    data = c._store.load()
+    if not data:
+        console.print("[yellow]未登录[/yellow]")
+        return
+    console.print(f"[green]已登录[/green]  {data.get('email', '')}")
+    console.print(f"Session 过期：{data.get('session_expires_at', 'N/A')}\n")
+    t = Table("别名", "系统", "Token 状态", "剩余时间(s)")
+    for s in c._registry.list_all():
+        r = c.check_token(s["alias"])
+        t.add_row(
+            s["alias"],
+            s["system_key"],
+            "[green]有效[/green]" if r["valid"] else "[red]无效/未获取[/red]",
+            str(r["expires_in"]),
+        )
+    console.print(t)
+    # 展示各系统已授权权限（从已缓存 JWT 解析）
+    store_data = c._store.load() or {}
+    tokens = store_data.get("tokens", {})
+    for s in c._registry.list_all():
+        td = tokens.get(s["system_key"])
+        if td and td.get("jwt"):
+            _display_scope(td["jwt"], s["alias"])
+
+
+# ── Token 操作 ─────────────────────────────────────────
+
+@token_app.command("get")
+def token_get(
+    system: str = typer.Option(..., "--system", "-s", help="系统别名"),
+):
+    """获取指定系统 JWT（纯文本输出，适合脚本）"""
+    try:
+        typer.echo(_client().get_token(system))
+    except (NotAuthenticatedError, SystemNotFoundError) as e:
+        console.print(f"[red]{e}[/red]", err=True)
+        raise typer.Exit(1)
+
+
+@token_app.command("check")
+def token_check(system: str = typer.Option(..., "--system", "-s")):
+    """检测指定系统 JWT 有效性"""
+    r = _client().check_token(system)
+    if r["valid"]:
+        console.print(f"[green]✓ 有效[/green]  剩余 {r['expires_in']} 秒")
+    else:
+        console.print("[red]✗ 已过期或未获取[/red]")
+        raise typer.Exit(1)
+
+
+@token_app.command("refresh")
+def token_refresh(
+    system: str = typer.Option(None, "--system", "-s"),
+    all_systems: bool = typer.Option(False, "--all"),
+):
+    """刷新 JWT（--system 指定单个，--all 刷新全部）"""
+    c = _client()
+    if all_systems:
+        for alias, st in c._tm.refresh_all().items():
+            icon = "[green]✓[/green]" if st == "ok" else "[red]✗[/red]"
+            console.print(f"{icon} {alias}: {st}")
+    elif system:
+        try:
+            c.refresh_token(system)
+            console.print(f"[green]✓ {system} JWT 已刷新[/green]")
+        except Exception as e:
+            console.print(f"[red]✗ {e}[/red]")
+            raise typer.Exit(1)
+    else:
+        console.print("[red]请指定 --system 或 --all[/red]")
+        raise typer.Exit(1)
+
+
+# ── 系统管理 ───────────────────────────────────────────
+
+@system_app.command("list")
+def system_list():
+    """列出所有已注册系统"""
+    t = Table("别名", "System Key", "URL", "来源")
+    for s in _registry().list_all():
+        t.add_row(s["alias"], s["system_key"], s["url"], s.get("source", ""))
+    console.print(t)
+
+
+@system_app.command("sync")
+def system_sync():
+    """从 ops 同步多实例系统列表"""
+    client = _client()
+    if not client.is_authenticated():
+        console.print("[red]未登录，请先运行: opscli auth login[/red]")
+        raise typer.Exit(1)
+    try:
+        resp = httpx.get(
+            f"{OPS_URL}/api/v1/cli/systems",
+            headers=client.build_session_headers("ops"),
+            timeout=10,
+        )
+        resp.raise_for_status()
+        systems = resp.json().get("systems", [])
+        _registry().sync_from_ops(systems)
+        console.print(f"[green]✓ 同步完成，共 {len(systems)} 个系统[/green]")
+    except Exception as e:
+        console.print(f"[red]✗ 同步失败: {e}[/red]")
+        raise typer.Exit(1)
+
+
+@system_app.command("add")
+def system_add(
+    alias: str = typer.Option(..., "--alias"),
+    url: str = typer.Option(..., "--url"),
+    key: str = typer.Option(None, "--key", help="存储键，默认由 alias 生成"),
+):
+    """手动添加系统实例（source=local）"""
+    system_key = key or alias.replace(" ", "_").lower()
+    _registry().add_local(alias, system_key, url)
+    console.print(f"[green]✓ 已添加：{alias}[/green]")
+
+
+@system_app.command("remove")
+def system_remove(alias: str = typer.Option(..., "--alias")):
+    """移除手动添加的系统"""
+    try:
+        _registry().remove(alias)
+        console.print(f"[green]✓ 已移除：{alias}[/green]")
+    except SystemNotFoundError as e:
+        console.print(f"[red]{e}[/red]")
+        raise typer.Exit(1)
+
+
+# ── 诊断 ───────────────────────────────────────────────
+
+@app.command()
+def doctor():
+    """检查登录状态与各系统连通性"""
+    c = _client()
+    console.print("[bold]opscli auth 环境检查\n[/bold]")
+    if c.is_authenticated():
+        console.print("[green]✓ 已登录[/green]")
+    else:
+        console.print("[red]✗ 未登录（运行 opscli auth login）[/red]")
+    for s in c._registry.list_all():
+        try:
+            httpx.get(s["url"], timeout=5)
+            console.print(f"[green]✓ {s['alias']} 可访问[/green]")
+        except Exception:
+            console.print(f"[red]✗ {s['alias']} 不可达 ({s['url']})[/red]")

opscli/auth/commands/__init__.py

@@ -0,0 +1 @@
+"""auth 命令层。"""

opscli/auth/commands/cli.py

@@ -0,0 +1,5 @@
+"""auth CLI 兼容实现。"""
+
+from opscli.auth.cli import app
+
+__all__ = ["app"]

opscli/auth/config.py

@@ -0,0 +1,55 @@
+import configparser
+from opscli.config import CONFIG_DIR
+
+# 默认配置（生产环境）
+DEFAULTS = {
+    "ops_url": "https://ops.api.qa.aukeyit.com/api",
+    "ops_system_url": "https://ops.api.qa.aukeyit.com",
+    "ops_token_endpoint": "/api/v1/auth/cli-token",
+    "polaris_system_url": "https://bi.api.test.aukeyit.com",
+    "polaris_token_endpoint": "/api/auth/cli-token",
+    "amazon_submit_endpoint": "",
+}
+
+CONFIG_PATH = CONFIG_DIR / "config.ini"
+
+
+def load_config() -> dict:
+    """读取配置文件，不存在则返回默认值"""
+    config = configparser.ConfigParser()
+    if CONFIG_PATH.exists():
+        config.read(CONFIG_PATH, encoding="utf-8")
+
+    section = "systems"
+    result = {}
+    for key, default in DEFAULTS.items():
+        result[key] = config.get(section, key, fallback=default)
+    return result
+
+
+def get_ops_url() -> str:
+    return load_config()["ops_url"]
+
+
+def get_builtin_systems() -> list[dict]:
+    cfg = load_config()
+    return [
+        {
+            "alias": "ops",
+            "system_key": "ops",
+            "url": cfg["ops_system_url"],
+            "token_endpoint": cfg["ops_token_endpoint"],
+            "source": "builtin",
+        },
+        {
+            "alias": "polaris",
+            "system_key": "polaris",
+            "url": cfg["polaris_system_url"],
+            "token_endpoint": cfg["polaris_token_endpoint"],
+            "source": "builtin",
+        },
+    ]
+
+
+def get_amazon_submit_endpoint() -> str:
+    return load_config()["amazon_submit_endpoint"]

opscli/auth/core/__init__.py

@@ -0,0 +1 @@
+# core 模块

opscli/auth/core/device_flow.py

@@ -0,0 +1,80 @@
+"""OAuth2 Device Flow 授权模块（RFC 8628）。
+
+实现 CLI 场景下的设备授权流程：
+1. 向后端请求设备码（device_code）和验证 URL
+2. 用户在浏览器中打开验证 URL 并输入验证码
+3. CLI 以固定间隔轮询后端，等待用户完成授权
+4. 授权成功后自动保存 session 到本地凭证存储
+"""
+import time
+import httpx
+from opscli.auth.exceptions import DeviceFlowExpiredError, DeviceFlowDeniedError
+
+
+class DeviceFlow:
+    """OAuth2 Device Flow 授权器，管理设备码获取与轮询等待。"""
+
+    def __init__(self, ops_url: str, store):
+        """
+        Args:
+            ops_url: 运营系统后端地址（如 https://ops.aukeys.com）
+            store: CredentialStore 实例，用于授权成功后持久化 session
+        """
+        self._url = ops_url.rstrip("/")
+        self._store = store
+
+    def request_device_code(self) -> dict:
+        """向后端请求设备码和验证信息。
+
+        Returns:
+            dict: 包含 device_code、user_code、verification_url、expires_in 等字段
+        """
+        resp = httpx.post(f"{self._url}/v1/cli/device/code", timeout=10)
+        resp.raise_for_status()
+        return resp.json()
+
+    def poll(self, device_code: str, interval: int = 3, max_wait: int = 300) -> dict:
+        """轮询后端等待用户完成授权。
+
+        以 interval 为间隔持续轮询，直到用户授权、拒绝或超时。
+        授权成功后自动调用 store.save_session() 持久化凭证。
+
+        Args:
+            device_code: 设备码，由 request_device_code() 返回
+            interval: 轮询间隔（秒），默认 3 秒，由后端返回的值决定
+            max_wait: 最大等待时间（秒），默认 300 秒（5 分钟）
+
+        Returns:
+            dict: 包含 session_id、email、expires_at 等授权信息
+
+        Raises:
+            DeviceFlowExpiredError: 设备码超时或等待超时
+            DeviceFlowDeniedError: 用户在浏览器中拒绝授权
+        """
+        elapsed = 0
+        while elapsed < max_wait:
+            time.sleep(interval)
+            elapsed += interval
+            resp = httpx.get(
+                f"{self._url}/v1/cli/device/poll",
+                params={"device_code": device_code},
+                timeout=10,
+            )
+            resp.raise_for_status()
+            body = resp.json()
+            status = body.get("status")
+            if status == "authorized":
+                # 授权成功，保存 session 到本地凭证存储
+                self._store.save_session(
+                    body["session_id"],
+                    body.get("email", ""),
+                    body.get("expires_at", ""),
+                    device_code=device_code,
+                )
+                return body
+            elif status == "expired":
+                raise DeviceFlowExpiredError("设备码已超时，请重新运行: opscli auth login")
+            elif status == "denied":
+                raise DeviceFlowDeniedError("用户拒绝授权")
+        # 超过最大等待时间仍未授权
+        raise DeviceFlowExpiredError("等待超时，请重新运行: opscli auth login")

opscli/auth/core/system_registry.py

@@ -0,0 +1,89 @@
+"""系统注册表模块。
+
+管理三类系统来源：
+- builtin：内置系统（ops/polaris），代码硬编码，不可删除（铁律9）
+- local：用户手动添加的系统，持久化到 systems.json
+- ops_sync：从运营系统后端同步的系统列表
+
+系统合并优先级：local/ops_sync > builtin（同别名时用户配置覆盖内置）。
+"""
+import json
+from pathlib import Path
+from opscli.auth.exceptions import SystemNotFoundError
+
+
+class SystemRegistry:
+    """系统注册表，管理内置、本地和远端同步的系统实例。"""
+
+    def __init__(self, base_dir: Path | None = None, builtin_systems: list | None = None):
+        """
+        Args:
+            base_dir: 配置存储目录，默认使用 CONFIG_DIR（~/.config/opscli/）
+            builtin_systems: 内置系统列表（由 auth/config.py 的 get_builtin_systems() 提供）
+        """
+        from opscli.config import CONFIG_DIR
+        base = Path(base_dir or CONFIG_DIR)
+        base.mkdir(parents=True, exist_ok=True)
+        self._path = base / "systems.json"
+        # 内置系统以 alias 为 key 构建字典，方便快速查找和去重
+        self._builtin = {s["alias"]: s for s in (builtin_systems or [])}
+
+    def _load(self) -> list:
+        """从 systems.json 加载用户自定义和远端同步的系统列表。"""
+        return json.loads(self._path.read_text()) if self._path.exists() else []
+
+    def _save(self, systems: list):
+        """将系统列表持久化到 systems.json。"""
+        self._path.write_text(json.dumps(systems, ensure_ascii=False, indent=2))
+
+    def list_all(self) -> list:
+        """返回所有系统（内置 + 用户配置），同别名时用户配置覆盖内置。"""
+        stored = {s["alias"]: s for s in self._load()}
+        # 合并策略：先 builtin 再 stored，stored 的同名项会覆盖 builtin
+        return list({**self._builtin, **stored}.values())
+
+    def get(self, alias: str) -> dict:
+        """按别名查找系统，找不到则抛出 SystemNotFoundError。"""
+        for s in self.list_all():
+            if s["alias"] == alias:
+                return s
+        raise SystemNotFoundError(f"系统 '{alias}' 未注册")
+
+    def add_local(self, alias: str, system_key: str, url: str,
+                  token_endpoint: str = "/api/auth/cli-token"):
+        """添加或更新用户自定义系统（source=local）。
+
+        如果同别名已存在，执行替换（upsert 语义）。
+        """
+        # 先移除同别名旧记录，再追加新记录
+        systems = [s for s in self._load() if s["alias"] != alias]
+        systems.append({
+            "alias": alias,
+            "system_key": system_key,
+            "url": url,
+            "token_endpoint": token_endpoint,
+            "source": "local",
+        })
+        self._save(systems)
+
+    def remove(self, alias: str):
+        """移除系统（仅限 local 类型，内置系统受保护不可删除）。"""
+        if alias in self._builtin:
+            raise SystemNotFoundError(f"内置系统 '{alias}' 不可删除")
+        self._save([s for s in self._load() if s["alias"] != alias])
+
+    def sync_from_ops(self, ops_systems: list):
+        """从运营系统后端同步系统列表。
+
+        合并策略：
+        - 保留所有非 ops_sync 来源的系统（builtin/local 不受影响）
+        - ops_sync 来源的系统以远端最新数据全量替换
+        """
+        existing = {s["alias"]: s for s in self._load()}
+        # 保留所有非 ops_sync 的条目
+        kept = {a: s for a, s in existing.items() if s.get("source") != "ops_sync"}
+        # 用远端数据填充（不覆盖 local/builtin 的同名条目）
+        for s in ops_systems:
+            if s["alias"] not in kept:
+                kept[s["alias"]] = {**s, "source": "ops_sync"}
+        self._save(list(kept.values()))

opscli/auth/core/token_manager.py

@@ -0,0 +1,167 @@
+"""JWT Token 管理模块。
+
+负责 Token 的获取、缓存、刷新和有效性检测。
+采用双层并发锁机制（铁律6）防止多进程/多线程重复获取 JWT：
+- Layer 1：threading.Lock（防同进程多线程并发）
+- Layer 2：fcntl.flock()（防多 CLI 进程并发，Windows 自动跳过）
+
+Token 生命周期三态：valid / needs_refresh / expired
+刷新阈值 REFRESH_THRESHOLD = 300s（距过期 5 分钟内触发）。
+"""
+import httpx
+import threading
+from datetime import datetime, timezone, timedelta
+from opscli.auth.exceptions import NotAuthenticatedError, TokenFetchError
+
+try:
+    import fcntl
+    _FCNTL_AVAILABLE = True
+except ImportError:
+    _FCNTL_AVAILABLE = False  # Windows 不支持 fcntl
+
+# 进程内线程锁：key = system_key
+_thread_locks: dict[str, threading.Lock] = {}
+_thread_locks_mutex = threading.Lock()
+
+
+def _get_thread_lock(key: str) -> threading.Lock:
+    with _thread_locks_mutex:
+        if key not in _thread_locks:
+            _thread_locks[key] = threading.Lock()
+        return _thread_locks[key]
+
+REFRESH_THRESHOLD = 300   # 距过期 5 分钟内触发刷新（原 30 分钟过于保守）
+MAX_JWT_TTL = 86400       # JWT 最大有效期 24 小时（86400 秒）
+
+
+class TokenManager:
+    """JWT Token 管理器，协调凭证存储和系统注册表完成 Token 生命周期管理。"""
+
+    def __init__(self, store, registry):
+        """
+        Args:
+            store: CredentialStore 实例，用于读写凭证
+            registry: SystemRegistry 实例，用于查找系统配置
+        """
+        self._store = store
+        self._registry = registry
+
+    def _get_session_id(self) -> str:
+        data = self._store.load()
+        if not data or not data.get("session_id"):
+            raise NotAuthenticatedError("未登录，请运行: opscli auth login")
+        exp = datetime.fromisoformat(data["session_expires_at"])
+        # 无时区信息时视为 UTC
+        if exp.tzinfo is None:
+            exp = exp.replace(tzinfo=timezone.utc)
+        if exp < datetime.now(timezone.utc):
+            raise NotAuthenticatedError("登录已过期，请重新运行: opscli auth login")
+        return data["session_id"]
+
+    def get_session_id(self) -> str:
+        """返回当前有效 session_id。
+
+        对外暴露公共接口，避免 SDK 直接依赖私有实现细节。
+        """
+        return self._get_session_id()
+
+    def token_status(self, token_data: dict) -> str:
+        """返回 Token 三态：valid / needs_refresh / expired"""
+        try:
+            exp = datetime.fromisoformat(token_data["expires_at"])
+            if exp.tzinfo is None:
+                exp = exp.replace(tzinfo=timezone.utc)
+            remaining = (exp - datetime.now(timezone.utc)).total_seconds()
+            if remaining > REFRESH_THRESHOLD:
+                return "valid"
+            if remaining > 0:
+                return "needs_refresh"
+            return "expired"
+        except (KeyError, ValueError):
+            return "expired"
+
+    def _is_valid(self, token_data: dict) -> bool:
+        """判断 Token 是否处于 valid 状态（无需刷新）。"""
+        return self.token_status(token_data) == "valid"
+
+    def _fetch_token(self, system_key: str, url: str, endpoint: str) -> str:
+        """向后端请求新的 JWT 并保存到凭证存储。"""
+        session_id = self.get_session_id()
+        try:
+            resp = httpx.post(
+                f"{url}{endpoint}",
+                json={"session_id": session_id},
+                timeout=10,
+            )
+            resp.raise_for_status()
+            body = resp.json()
+            # 后端返回的 expires_in 可能超出合理范围，限制为最大 24 小时
+            expires_in = min(body.get("expires_in", 7200), MAX_JWT_TTL)
+            self._store.save_token(system_key, body["jwt"], expires_in)
+            return body["jwt"]
+        except httpx.HTTPStatusError as e:
+            raise TokenFetchError(f"获取 {system_key} JWT 失败: {e.response.status_code}")
+        except Exception as e:
+            raise TokenFetchError(f"获取 {system_key} JWT 异常: {e}")
+
+    def get_token(self, alias: str) -> str:
+        sys = self._registry.get(alias)
+        system_key = sys["system_key"]
+
+        # 层1：进程内线程锁，防止同进程多线程并发重复换取
+        thread_lock = _get_thread_lock(system_key)
+        with thread_lock:
+            # 双重检查：可能其他线程已完成刷新
+            data = self._store.load() or {}
+            td = data.get("tokens", {}).get(system_key)
+            if td and self._is_valid(td):
+                return td["jwt"]
+
+            # 层2：跨进程文件锁，防止多个 CLI 进程并发重复换取
+            if _FCNTL_AVAILABLE:
+                lock_path = self._store.base_dir / f".lock_{system_key}"
+                with open(lock_path, "w") as lf:
+                    try:
+                        fcntl.flock(lf, fcntl.LOCK_EX)
+                        # 再次双重检查：其他进程可能已完成刷新
+                        data = self._store.load() or {}
+                        td = data.get("tokens", {}).get(system_key)
+                        if td and self._is_valid(td):
+                            return td["jwt"]
+                        return self._fetch_token(system_key, sys["url"], sys["token_endpoint"])
+                    finally:
+                        fcntl.flock(lf, fcntl.LOCK_UN)
+            else:
+                return self._fetch_token(system_key, sys["url"], sys["token_endpoint"])
+
+    def check_token(self, alias: str) -> dict:
+        """检查指定系统 Token 有效性，返回 {valid: bool, expires_in: int}。"""
+        sys = self._registry.get(alias)
+        data = self._store.load() or {}
+        td = data.get("tokens", {}).get(sys["system_key"])
+        if not td:
+            return {"valid": False, "expires_in": 0}
+        try:
+            exp = datetime.fromisoformat(td["expires_at"])
+            if exp.tzinfo is None:
+                exp = exp.replace(tzinfo=timezone.utc)
+            rem = int((exp - datetime.now(timezone.utc)).total_seconds())
+            return {"valid": rem > 0, "expires_in": max(0, rem)}
+        except (KeyError, ValueError):
+            return {"valid": False, "expires_in": 0}
+
+    def refresh_token(self, alias: str) -> str:
+        """强制刷新指定系统的 JWT（忽略缓存有效期）。"""
+        sys = self._registry.get(alias)
+        return self._fetch_token(sys["system_key"], sys["url"], sys["token_endpoint"])
+
+    def refresh_all(self) -> dict:
+        """刷新所有已注册系统的 JWT，返回 {alias: "ok"/"失败: 原因"} 字典。"""
+        results = {}
+        for sys in self._registry.list_all():
+            try:
+                self._fetch_token(sys["system_key"], sys["url"], sys["token_endpoint"])
+                results[sys["alias"]] = "ok"
+            except Exception as e:
+                results[sys["alias"]] = f"失败: {e}"
+        return results

opscli/auth/domain/__init__.py

@@ -0,0 +1,23 @@
+"""auth 领域异常。"""
+
+from opscli.auth.domain.exceptions import (
+    AuthError,
+    DeviceFlowDeniedError,
+    DeviceFlowError,
+    DeviceFlowExpiredError,
+    NotAuthenticatedError,
+    SessionExpiredError,
+    SystemNotFoundError,
+    TokenFetchError,
+)
+
+__all__ = [
+    "AuthError",
+    "NotAuthenticatedError",
+    "SessionExpiredError",
+    "TokenFetchError",
+    "SystemNotFoundError",
+    "DeviceFlowError",
+    "DeviceFlowExpiredError",
+    "DeviceFlowDeniedError",
+]