illusion-code 0.1.0__py3-none-any.whl

illusion/auth/manager.py

@@ -0,0 +1,214 @@
+"""
+统一认证管理器模块
+==================
+
+本模块为 IllusionCode 提供统一的认证状态管理功能。
+
+主要功能：
+    - 管理环境（env_N）认证状态
+    - 切换和配置环境
+    - 存储和加载凭据（按 env_N 分组）
+
+类说明：
+    - AuthManager: 认证管理器类，负责所有认证相关的操作
+
+使用示例：
+    >>> from illusion.auth import AuthManager
+    >>> manager = AuthManager()
+    >>> status = manager.get_env_credential_statuses()
+    >>> print(status)
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from illusion.auth.storage import (
+    clear_env_credentials,
+    load_env_credential,
+    store_env_credential,
+)
+from illusion.config.i18n import t as _t
+
+log = logging.getLogger(__name__)
+
+
+class AuthManager:
+    """认证管理器
+
+    通过 :mod:`illusion.auth.storage` 读写凭据，
+    并通过设置跟踪当前活动的环境。
+    """
+
+    def __init__(self, settings: Any | None = None) -> None:
+        self._settings = settings
+
+    @property
+    def settings(self) -> Any:
+        """获取设置对象（延迟加载）"""
+        if self._settings is None:
+            from illusion.config import load_settings
+            self._settings = load_settings()
+        return self._settings
+
+    def get_active_env_key(self) -> str:
+        """获取当前活动的环境键名（如 "env_1"）"""
+        return self.settings._active_env_key
+
+    def list_envs(self) -> dict[str, Any]:
+        """获取所有环境配置"""
+        return self.settings.list_envs()
+
+    def get_env_credential_statuses(self) -> dict[str, Any]:
+        """获取所有环境的凭据状态
+
+        返回以 env_key 为键的字典::
+
+            {
+                "env_1": {
+                    "api_format": "anthropic",
+                    "base_url": "...",
+                    "model": "claude-sonnet-4-6",
+                    "has_credential": True,
+                    "active": True,
+                },
+                ...
+            }
+        """
+        active_env_key = self.get_active_env_key()
+        envs = self.list_envs()
+        result: dict[str, Any] = {}
+
+        for env_key, env in envs.items():
+            models = env.list_models()
+            model_name = next(iter(models.values())) if models else "(无模型)"
+            has_cred = bool(load_env_credential(env_key, "api_key")) or bool(env.api_key)
+            result[env_key] = {
+                "api_format": env.api_format,
+                "base_url": env.base_url or "",
+                "model": model_name,
+                "has_credential": has_cred,
+                "active": env_key == active_env_key,
+            }
+
+        return result
+
+    def save_settings(self) -> None:
+        """保存内存中的设置到持久化存储"""
+        from illusion.config import save_settings
+        save_settings(self.settings)
+
+    def use_env(self, env_key: str) -> None:
+        """切换到指定的环境
+
+        Args:
+            env_key: 环境键名（如 "env_1"）
+
+        Raises:
+            ValueError: 环境不存在
+        """
+        env = self.settings.get_env(env_key)
+        if env is None:
+            raise ValueError(_t("unknown_env", env_key=env_key))
+        models = env.list_models()
+        if models:
+            model_key = next(iter(models.keys()))
+            self.settings.model = f"{env_key}.{model_key}"
+        else:
+            self.settings.model = f"{env_key}.model_1"
+        self._settings = self.settings
+        self.save_settings()
+        log.info("已切换到环境 %s", env_key)
+
+    def update_env(
+        self,
+        env_key: str,
+        *,
+        api_format: str | None = None,
+        base_url: str | None = None,
+        api_key: str | None = None,
+    ) -> None:
+        """更新环境配置
+
+        Args:
+            env_key: 环境键名
+            api_format: API 格式
+            base_url: 基础 URL
+            api_key: API 密钥
+
+        Raises:
+            ValueError: 环境不存在
+        """
+        env = self.settings.get_env(env_key)
+        if env is None:
+            raise ValueError(_t("unknown_env", env_key=env_key))
+        updates: dict[str, Any] = {}
+        if api_format is not None:
+            updates["api_format"] = api_format
+        if base_url is not None:
+            updates["base_url"] = base_url
+        if api_key is not None:
+            updates["api_key"] = api_key
+        if updates:
+            updated_env = env.model_copy(update=updates)
+            setattr(self.settings, env_key, updated_env)
+            self._settings = self.settings
+            self.save_settings()
+
+    def remove_env(self, env_key: str) -> None:
+        """移除环境配置
+
+        Args:
+            env_key: 环境键名
+
+        Raises:
+            ValueError: 环境不存在或正在使用
+        """
+        if env_key == self.get_active_env_key():
+            raise ValueError(_t("cannot_remove_active_env"))
+        envs = self.settings.list_envs()
+        if env_key not in envs:
+            raise ValueError(_t("unknown_env", env_key=env_key))
+        extras = dict(self.settings.model_extra or {})
+        if env_key in extras:
+            del extras[env_key]
+            self._settings = self.settings.model_copy(update=extras)
+            self.save_settings()
+
+    def store_env_api_key(self, env_key: str, api_key: str) -> None:
+        """存储环境的 API 密钥到 credentials.json
+
+        Args:
+            env_key: 环境键名（如 "env_1"）
+            api_key: API 密钥
+        """
+        store_env_credential(env_key, "api_key", api_key)
+
+    def clear_env_api_key(self, env_key: str) -> None:
+        """删除环境的 API 密钥
+
+        Args:
+            env_key: 环境键名（如 "env_1"）
+        """
+        clear_env_credentials(env_key)
+
+    def store_credential(self, provider: str, key: str, value: str) -> None:
+        """存储凭据（兼容旧接口，按 provider 存储）
+
+        Args:
+            provider: 提供商名称
+            key: 键名
+            value: 凭据值
+        """
+        from illusion.auth.storage import store_credential
+        store_credential(provider, key, value)
+
+    def clear_credential(self, provider: str) -> None:
+        """删除凭据（兼容旧接口，按 provider 清除）
+
+        Args:
+            provider: 提供商名称
+        """
+        from illusion.auth.storage import clear_provider_credentials
+        clear_provider_credentials(provider)

illusion/auth/storage.py

@@ -0,0 +1,372 @@
+"""
+安全凭据存储模块
+================
+
+本模块为 IllusionCode 提供安全的凭据存储功能。
+
+默认后端：~/.illusion/credentials.json，权限 600
+可选后端：系统 keyring（如果安装了 keyring 包）
+
+函数说明：
+    - store_credential: 存储凭据
+    - load_credential: 加载凭据
+    - clear_provider_credentials: 清除提供商凭据
+    - store_external_binding/load_external_binding: 外部绑定存储/加载
+    - encrypt/decrypt: 轻量级混淆加密
+
+使用示例：
+    >>> from illusion.auth.storage import store_credential, load_credential
+    >>> store_credential("anthropic", "api_key", "sk-...")
+    >>> key = load_credential("anthropic", "api_key")
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from typing import Any
+
+from illusion.config.paths import get_config_dir
+
+# 模块级日志记录器
+log = logging.getLogger(__name__)
+
+# 常量定义
+_CREDS_FILE_NAME = "credentials.json"  # 凭据文件名
+_KEYRING_SERVICE = "illusion"  # keyring 服务名
+
+
+@dataclass(frozen=True)
+class ExternalAuthBinding:
+    """指向外部 CLI 管理的凭据的指针
+    
+    Attributes:
+        provider: 提供商名称
+        source_path: 源路径
+        source_kind: 源类型
+        managed_by: 管理程序
+        profile_label: 配置标签
+    """
+
+    provider: str
+    source_path: str
+    source_kind: str
+    managed_by: str
+    profile_label: str = ""
+
+
+# ---------------------------------------------------------------------------
+# 文件后端（始终可用）
+# ---------------------------------------------------------------------------
+
+
+def _creds_path() -> Path:
+    """获取凭据文件路径"""
+    return get_config_dir() / _CREDS_FILE_NAME
+
+
+def _load_creds_file() -> dict[str, Any]:
+    """加载凭据文件
+    
+    Returns:
+        dict[str, Any]: 凭据数据字典
+    """
+    path = _creds_path()
+    if not path.exists():
+        return {}
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError) as exc:
+        log.warning("Failed to read credentials file: %s", exc)
+        return {}
+
+
+def _save_creds_file(data: dict[str, Any]) -> None:
+    """保存凭据文件
+    
+    Args:
+        data: 凭据数据字典
+    """
+    path = _creds_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")
+    try:
+        path.chmod(0o600)
+    except OSError:
+        pass
+
+
+# ---------------------------------------------------------------------------
+# Keyring 后端（可选）
+# ---------------------------------------------------------------------------
+
+
+def _keyring_available() -> bool:
+    """检查 keyring 是否可用
+    
+    Returns:
+        bool: keyring 是否可用
+    """
+    try:
+        import keyring  # noqa: F401
+
+        return True
+    except ImportError:
+        return False
+
+
+def _keyring_key(provider: str, key: str) -> str:
+    """生成 keyring 键
+    
+    Args:
+        provider: 提供商名称
+        key: 键名
+    
+    Returns:
+        str: 组合键名
+    """
+    return f"{provider}:{key}"
+
+
+# ---------------------------------------------------------------------------
+# 公共 API
+# ---------------------------------------------------------------------------
+
+
+def store_credential(provider: str, key: str, value: str, *, use_keyring: bool | None = None) -> None:
+    """持久化 provider 下的凭据
+    
+    如果未设置 use_keyring，在可用时使用 keyring。
+    
+    Args:
+        provider: 提供商名称
+        key: 键名
+        value: 凭据值
+        use_keyring: 是否使用 keyring（可选）
+    """
+    if use_keyring is None:
+        use_keyring = _keyring_available()
+
+    if use_keyring:
+        try:
+            import keyring
+
+            keyring.set_password(_KEYRING_SERVICE, _keyring_key(provider, key), value)
+            log.debug("Stored %s/%s in keyring", provider, key)
+            return
+        except Exception as exc:
+            log.warning("Keyring store failed, falling back to file: %s", exc)
+
+    data = _load_creds_file()
+    data.setdefault(provider, {})[key] = value
+    _save_creds_file(data)
+    log.debug("Stored %s/%s in credentials file", provider, key)
+
+
+def load_credential(provider: str, key: str, *, use_keyring: bool | None = None) -> str | None:
+    """返回存储的凭据，未找到返回 None
+    
+    Args:
+        provider: 提供商名称
+        key: 键名
+        use_keyring: 是否使用 keyring（可选）
+    
+    Returns:
+        str | None: 凭据值或 None
+    """
+    if use_keyring is None:
+        use_keyring = _keyring_available()
+
+    if use_keyring:
+        try:
+            import keyring
+
+            value = keyring.get_password(_KEYRING_SERVICE, _keyring_key(provider, key))
+            if value is not None:
+                return value
+        except Exception as exc:
+            log.warning("Keyring load failed, falling back to file: %s", exc)
+
+    data = _load_creds_file()
+    return data.get(provider, {}).get(key)
+
+
+def clear_provider_credentials(provider: str, *, use_keyring: bool | None = None) -> None:
+    """删除 provider 的所有存储凭据
+    
+    Args:
+        provider: 提供商名称
+        use_keyring: 是否使用 keyring（可选）
+    """
+    if use_keyring is None:
+        use_keyring = _keyring_available()
+
+    if use_keyring:
+        try:
+            import keyring
+            from keyring.errors import PasswordDeleteError
+
+            # 尝试常见键；静默忽略缺失的
+            for key in ("api_key", "token", "github_token"):
+                try:
+                    keyring.delete_password(_KEYRING_SERVICE, _keyring_key(provider, key))
+                except (PasswordDeleteError, Exception):
+                    pass
+        except ImportError:
+            pass
+
+    data = _load_creds_file()
+    if provider in data:
+        del data[provider]
+        _save_creds_file(data)
+    log.debug("Cleared credentials for provider: %s", provider)
+
+
+def list_stored_providers() -> list[str]:
+    """返回文件中存储了凭据的提供商列表
+
+    Returns:
+        list[str]: 提供商名称列表
+    """
+    return list(_load_creds_file().keys())
+
+
+# ---------------------------------------------------------------------------
+# env_N 凭据存储（按环境分组）
+# ---------------------------------------------------------------------------
+
+
+def store_env_credential(env_key: str, key: str, value: str) -> None:
+    """按 env_N 分组存储凭据
+
+    Args:
+        env_key: 环境键名（如 "env_1"）
+        key: 键名（如 "api_key"）
+        value: 凭据值
+    """
+    data = _load_creds_file()
+    data.setdefault(env_key, {})[key] = value
+    _save_creds_file(data)
+    log.debug("Stored %s/%s in credentials file (env)", env_key, key)
+
+
+def load_env_credential(env_key: str, key: str) -> str | None:
+    """按 env_N 读取凭据，未找到返回 None
+
+    Args:
+        env_key: 环境键名（如 "env_1"）
+        key: 键名（如 "api_key"）
+
+    Returns:
+        str | None: 凭据值或 None
+    """
+    data = _load_creds_file()
+    return data.get(env_key, {}).get(key)
+
+
+def clear_env_credentials(env_key: str) -> None:
+    """删除 env_N 的所有存储凭据
+
+    Args:
+        env_key: 环境键名（如 "env_1"）
+    """
+    data = _load_creds_file()
+    if env_key in data:
+        del data[env_key]
+        _save_creds_file(data)
+    log.debug("Cleared credentials for env: %s", env_key)
+
+
+def store_external_binding(binding: ExternalAuthBinding) -> None:
+    """持久化描述 provider 外部认证源的元数据
+    
+    Args:
+        binding: 外部认证绑定
+    """
+    data = _load_creds_file()
+    entry = data.setdefault(binding.provider, {})
+    entry["external_binding"] = asdict(binding)
+    _save_creds_file(data)
+    log.debug("Stored external auth binding for provider: %s", binding.provider)
+
+
+def load_external_binding(provider: str) -> ExternalAuthBinding | None:
+    """如果存在，加载 provider 的外部认证绑定元数据
+    
+    Args:
+        provider: 提供商名称
+    
+    Returns:
+        ExternalAuthBinding | None: 外部绑定或 None
+    """
+    entry = _load_creds_file().get(provider, {})
+    if not isinstance(entry, dict):
+        return None
+    raw = entry.get("external_binding")
+    if not isinstance(raw, dict):
+        return None
+    try:
+        return ExternalAuthBinding(
+            provider=str(raw["provider"]),
+            source_path=str(raw["source_path"]),
+            source_kind=str(raw["source_kind"]),
+            managed_by=str(raw["managed_by"]),
+            profile_label=str(raw.get("profile_label", "") or ""),
+        )
+    except KeyError:
+        log.warning("Ignoring malformed external auth binding for provider: %s", provider)
+        return None
+
+
+# ---------------------------------------------------------------------------
+# 加密/解密辅助函数（轻量级 XOR 混淆，非真正加密）
+# ---------------------------------------------------------------------------
+
+
+def _obfuscation_key() -> bytes:
+    """返回从主目录路径派生的每用户混淆密钥
+    
+    Returns:
+        bytes: 32 字节混淆密钥
+    """
+    seed = str(Path.home()).encode() + b"illusion-v1"
+    # 通过 SHA-256 简单重复密钥拉伸到 32 字节以保持确定性
+    import hashlib
+
+    return hashlib.sha256(seed).digest()
+
+
+def encrypt(plaintext: str) -> str:
+    """轻量级混淆 plaintext（base64 编码 XOR）。非加密。
+    
+    Args:
+        plaintext: 明文
+    
+    Returns:
+        str: 混淆后的字符串
+    """
+    import base64
+
+    key = _obfuscation_key()
+    data = plaintext.encode("utf-8")
+    xored = bytes(b ^ key[i % len(key)] for i, b in enumerate(data))
+    return base64.urlsafe_b64encode(xored).decode("ascii")
+
+
+def decrypt(ciphertext: str) -> str:
+    """encrypt 的反向操作
+    
+    Args:
+        ciphertext: 混淆的字符串
+    
+    Returns:
+        str: 明文
+    """
+    import base64
+
+    key = _obfuscation_key()
+    data = base64.urlsafe_b64decode(ciphertext.encode("ascii"))
+    xored = bytes(b ^ key[i % len(key)] for i, b in enumerate(data))
+    return xored.decode("utf-8")

illusion/bridge/__init__.py

@@ -0,0 +1,38 @@
+"""
+桥接模块
+========
+
+本模块提供 IllusionCode 桥接会话管理功能。
+
+主要组件：
+    - BridgeSessionManager: 桥接会话管理器
+    - BridgeSessionRecord: 桥接会话记录
+    - BridgeConfig: 桥接配置
+    - SessionHandle: 会话句柄
+    - WorkData: 工作数据
+    - WorkSecret: 工作密钥
+    - get_bridge_manager: 获取桥接管理器
+    - spawn_session: 生成会话
+
+使用示例：
+    >>> from illusion.bridge import BridgeSessionManager, spawn_session
+"""
+
+from illusion.bridge.manager import BridgeSessionManager, BridgeSessionRecord, get_bridge_manager
+from illusion.bridge.session_runner import SessionHandle, spawn_session
+from illusion.bridge.types import BridgeConfig, WorkData, WorkSecret
+from illusion.bridge.work_secret import build_sdk_url, decode_work_secret, encode_work_secret
+
+__all__ = [
+    "BridgeSessionManager",
+    "BridgeSessionRecord",
+    "BridgeConfig",
+    "SessionHandle",
+    "WorkData",
+    "WorkSecret",
+    "build_sdk_url",
+    "decode_work_secret",
+    "encode_work_secret",
+    "get_bridge_manager",
+    "spawn_session",
+]