remote-cmd-manager 2.3.0__tar.gz → 2.5.0__tar.gz

{remote_cmd_manager-2.3.0/remote_cmd_manager.egg-info → remote_cmd_manager-2.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: remote_cmd_manager
-Version: 2.3.0
+Version: 2.5.0
 Summary: Cross-platform SSH remote server management tool (Linux/macOS/Windows) — lightweight, zero-configuration CLI and Python API for managing servers over SSH. Supports host CRUD, batch commands, file transfer, credential encryption, async execution, and more.
 Author-email: Vae-Scrooge <vaescrooge@gmail.com>
 License: MIT
@@ -15,7 +15,6 @@ Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: System Administrators
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
@@ -27,17 +26,17 @@ Classifier: Environment :: Console
 Classifier: Operating System :: POSIX :: Linux
 Classifier: Operating System :: MacOS
 Classifier: Operating System :: Microsoft :: Windows
-Requires-Python: >=3.9
+Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: paramiko>=3.0
+Requires-Dist: paramiko<6,>=5.0
 Requires-Dist: click>=8.0
 Requires-Dist: cryptography>=41.0
 Requires-Dist: rich>=13.0
 Requires-Dist: PyYAML>=6.0
 Requires-Dist: aiofiles>=3.0
 Provides-Extra: async
-Requires-Dist: asyncssh>=2.14.0; extra == "async"
+Requires-Dist: asyncssh<3,>=2.24.0; extra == "async"
 Provides-Extra: cloud
 Requires-Dist: boto3>=1.34; extra == "cloud"
 Provides-Extra: dev
@@ -46,6 +45,7 @@ Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
 Requires-Dist: pytest-cov>=4.0; extra == "dev"
 Requires-Dist: ruff>=0.4; extra == "dev"
 Requires-Dist: mypy>=1.10; extra == "dev"
+Requires-Dist: asyncssh<3,>=2.24.0; extra == "dev"
 Requires-Dist: keyring>=24.0; extra == "dev"
 Provides-Extra: docs
 Requires-Dist: pdoc==15.0.4; extra == "docs"
@@ -55,7 +55,7 @@ Dynamic: license-file
   <img src="https://img.shields.io/pypi/v/remote_cmd_manager?style=for-the-badge&logo=pypi&logoColor=white&label=PyPI" alt="PyPI">
   <img src="https://img.shields.io/pypi/dm/remote_cmd_manager?style=for-the-badge&logo=python&logoColor=white&label=Downloads" alt="Downloads">
   <img src="https://img.shields.io/github/stars/Vae-Scrooge/remote-cmd?style=for-the-badge&logo=github" alt="Stars">
-  <img src="https://img.shields.io/badge/python-3.9%2B-blue?style=for-the-badge&logo=python" alt="Python">
+  <img src="https://img.shields.io/badge/python-3.10%2B-blue?style=for-the-badge&logo=python" alt="Python">
   <img src="https://img.shields.io/github/license/Vae-Scrooge/remote-cmd?style=for-the-badge" alt="License">
   <img src="https://img.shields.io/github/actions/workflow/status/Vae-Scrooge/remote-cmd/ci.yml?style=for-the-badge&logo=githubactions&label=CI" alt="CI">
 </p>
@@ -89,28 +89,36 @@ pip install remote_cmd_manager && remote-cmd host add web-01 192.168.1.10 ubuntu
 
 ---
 
-## v2.3.0 Release Highlights
+## v2.5.0 Release Highlights
 
-v2.3.0 makes blocking SFTP operations timeout-safe, hardens async cancellation cleanup,
-and aligns the supported Python range and release tooling. See the
+v2.5.0 is a hardening and scalability release: dependency security floors, Python 3.9
+removal, bounded async scheduling, and explicit output-retention / credential-persistence
+policies. Backward-compatible defaults are preserved where behavior is involved. See the
 [full migration notes](./CHANGELOG.md) before upgrading automated callers.
 
-### SFTP Timeouts & Reliability
+### Security & Platform
 
-- Blocking SFTP operations now support an inactivity timeout (default: `ConnectionConfig.timeout`, 30 s): uploads, downloads, directory listing, directory creation, removal, and file-info calls accept an optional `timeout` argument.
-- The synchronous `SSHClient` applies the timeout to the Paramiko SFTP channel, so a stalled read/write aborts the actual operation and raises `SSHFileTransferError`.
-- The asynchronous `AsyncSSHClient` bounds SFTP channel startup with a timeout and uses a progress-based inactivity watchdog to cancel stalled transfers, awaiting the aborted operation and preserving caller cancellation during cleanup.
-- Timed-out or cancelled SFTP sessions are closed and discarded, so a stale or desynchronized channel can never be reused.
+- Minimum supported Python is now **3.10** (3.9 reached EOL on 2025-10-31).
+- Security floors raised: **Paramiko >= 5.0,<6** and **AsyncSSH >= 2.24.0,<3** (2.23.x and earlier are affected by 2026 AsyncSSH advisories).
 
-### Release Engineering
+### Scalability
 
-- Python 3.9–3.14 are officially supported and CI-tested; `Requires-Python` remains `>=3.9`.
-- CI runs release-metadata validation for CHANGELOG.md-only changes.
-- Publish builds pin `build==1.5.0` and `twine==7.0.0`.
+- `AsyncBatchExecutor` now uses a **bounded worker queue**: only `min(max_concurrency, host count)` worker tasks are created instead of one task per host, so scheduling memory no longer grows with fleet size.
+- New `OutputPolicy` (exported from `remote_cmd`) gives an explicit, mutually exclusive alternative to `max_output_bytes`; `None` still means full retention in v2.5, and a bounded default is planned for v3.0.
+
+### Credential Safety
+
+- `JsonHostRepository` / `SqliteHostRepository` accept `allow_plaintext_credentials` (default `None`): plaintext persistence now emits `PlaintextCredentialWarning`; pass `True` to opt in silently or `False` to reject it with `CredentialError`. v3.0 plans to reject by default.
+- JSON repository concurrency semantics are now explicit: single-process/single-writer; use SQLite for multi-process writers.
+- The `dev` extra now includes `asyncssh`, so `pip install -e ".[dev]"` runs the full test suite out of the box.
+
+### Compatibility
+
+- `max_output_bytes=None` still retains full output, and the public `BatchResult` / `BatchHostResult` schemas are unchanged; the legacy `max_output_bytes` parameter continues to work alongside `OutputPolicy`.
 
 ## Table of Contents
 
-- [v2.3.0 Release Highlights](#v230-release-highlights)
+- [v2.5.0 Release Highlights](#v250-release-highlights)
 - [Why Remote CMD?](#why-remote-cmd)
 - [Quick Start](#quick-start)
 - [Use Cases](#use-cases)
@@ -258,7 +266,7 @@ with SSHClient(config) as client:
 | **File Transfer** | Upload/download via SFTP (`remote-cmd upload/download`) |
 | **Host Management** | CRUD with pluggable JSON or **SQLite** persistence |
 | **Tag System** | Filter hosts by tag (e.g., `production`, `web`, `db`) |
-| **Batch Ops** | Run commands across any host group, synchronously or asynchronously |
+| **Batch Ops** | Run commands across any host group, synchronously or asynchronously; optional per-host retained-output cap (`max_output_bytes`) |
 | **Async Kernel** | `AsyncSSHClient` / `AsyncConnectionPool` / `AsyncBatchExecutor` via the `[async]` extra |
 | **Task Runner** | Track and schedule long-running remote tasks with statuses (`TaskRunner`) |
 | **Connection Test** | Test all host SSH connections and report status |
@@ -348,7 +356,7 @@ Good first issues are labelled `good first issue` in the
 developed independently as a focused alternative to heavyweight tools for the
 ad-hoc SSH tasks that come up in day-to-day server work.
 
-- **Project health:** CI runs on every PR, Python 3.9+ is supported, and the
+- **Project health:** CI runs on every PR, Python 3.10+ is supported, and the
   public API is versioned under [semantic versioning](https://semver.org/).
 - **Your code, your servers:** usage stays open under the MIT license — nothing
   is telemetry-driven or locked behind a service.

{remote_cmd_manager-2.3.0 → remote_cmd_manager-2.5.0}/README.md

@@ -2,7 +2,7 @@
   <img src="https://img.shields.io/pypi/v/remote_cmd_manager?style=for-the-badge&logo=pypi&logoColor=white&label=PyPI" alt="PyPI">
   <img src="https://img.shields.io/pypi/dm/remote_cmd_manager?style=for-the-badge&logo=python&logoColor=white&label=Downloads" alt="Downloads">
   <img src="https://img.shields.io/github/stars/Vae-Scrooge/remote-cmd?style=for-the-badge&logo=github" alt="Stars">
-  <img src="https://img.shields.io/badge/python-3.9%2B-blue?style=for-the-badge&logo=python" alt="Python">
+  <img src="https://img.shields.io/badge/python-3.10%2B-blue?style=for-the-badge&logo=python" alt="Python">
   <img src="https://img.shields.io/github/license/Vae-Scrooge/remote-cmd?style=for-the-badge" alt="License">
   <img src="https://img.shields.io/github/actions/workflow/status/Vae-Scrooge/remote-cmd/ci.yml?style=for-the-badge&logo=githubactions&label=CI" alt="CI">
 </p>
@@ -36,28 +36,36 @@ pip install remote_cmd_manager && remote-cmd host add web-01 192.168.1.10 ubuntu
 
 ---
 
-## v2.3.0 Release Highlights
+## v2.5.0 Release Highlights
 
-v2.3.0 makes blocking SFTP operations timeout-safe, hardens async cancellation cleanup,
-and aligns the supported Python range and release tooling. See the
+v2.5.0 is a hardening and scalability release: dependency security floors, Python 3.9
+removal, bounded async scheduling, and explicit output-retention / credential-persistence
+policies. Backward-compatible defaults are preserved where behavior is involved. See the
 [full migration notes](./CHANGELOG.md) before upgrading automated callers.
 
-### SFTP Timeouts & Reliability
+### Security & Platform
 
-- Blocking SFTP operations now support an inactivity timeout (default: `ConnectionConfig.timeout`, 30 s): uploads, downloads, directory listing, directory creation, removal, and file-info calls accept an optional `timeout` argument.
-- The synchronous `SSHClient` applies the timeout to the Paramiko SFTP channel, so a stalled read/write aborts the actual operation and raises `SSHFileTransferError`.
-- The asynchronous `AsyncSSHClient` bounds SFTP channel startup with a timeout and uses a progress-based inactivity watchdog to cancel stalled transfers, awaiting the aborted operation and preserving caller cancellation during cleanup.
-- Timed-out or cancelled SFTP sessions are closed and discarded, so a stale or desynchronized channel can never be reused.
+- Minimum supported Python is now **3.10** (3.9 reached EOL on 2025-10-31).
+- Security floors raised: **Paramiko >= 5.0,<6** and **AsyncSSH >= 2.24.0,<3** (2.23.x and earlier are affected by 2026 AsyncSSH advisories).
 
-### Release Engineering
+### Scalability
 
-- Python 3.9–3.14 are officially supported and CI-tested; `Requires-Python` remains `>=3.9`.
-- CI runs release-metadata validation for CHANGELOG.md-only changes.
-- Publish builds pin `build==1.5.0` and `twine==7.0.0`.
+- `AsyncBatchExecutor` now uses a **bounded worker queue**: only `min(max_concurrency, host count)` worker tasks are created instead of one task per host, so scheduling memory no longer grows with fleet size.
+- New `OutputPolicy` (exported from `remote_cmd`) gives an explicit, mutually exclusive alternative to `max_output_bytes`; `None` still means full retention in v2.5, and a bounded default is planned for v3.0.
+
+### Credential Safety
+
+- `JsonHostRepository` / `SqliteHostRepository` accept `allow_plaintext_credentials` (default `None`): plaintext persistence now emits `PlaintextCredentialWarning`; pass `True` to opt in silently or `False` to reject it with `CredentialError`. v3.0 plans to reject by default.
+- JSON repository concurrency semantics are now explicit: single-process/single-writer; use SQLite for multi-process writers.
+- The `dev` extra now includes `asyncssh`, so `pip install -e ".[dev]"` runs the full test suite out of the box.
+
+### Compatibility
+
+- `max_output_bytes=None` still retains full output, and the public `BatchResult` / `BatchHostResult` schemas are unchanged; the legacy `max_output_bytes` parameter continues to work alongside `OutputPolicy`.
 
 ## Table of Contents
 
-- [v2.3.0 Release Highlights](#v230-release-highlights)
+- [v2.5.0 Release Highlights](#v250-release-highlights)
 - [Why Remote CMD?](#why-remote-cmd)
 - [Quick Start](#quick-start)
 - [Use Cases](#use-cases)
@@ -205,7 +213,7 @@ with SSHClient(config) as client:
 | **File Transfer** | Upload/download via SFTP (`remote-cmd upload/download`) |
 | **Host Management** | CRUD with pluggable JSON or **SQLite** persistence |
 | **Tag System** | Filter hosts by tag (e.g., `production`, `web`, `db`) |
-| **Batch Ops** | Run commands across any host group, synchronously or asynchronously |
+| **Batch Ops** | Run commands across any host group, synchronously or asynchronously; optional per-host retained-output cap (`max_output_bytes`) |
 | **Async Kernel** | `AsyncSSHClient` / `AsyncConnectionPool` / `AsyncBatchExecutor` via the `[async]` extra |
 | **Task Runner** | Track and schedule long-running remote tasks with statuses (`TaskRunner`) |
 | **Connection Test** | Test all host SSH connections and report status |
@@ -295,7 +303,7 @@ Good first issues are labelled `good first issue` in the
 developed independently as a focused alternative to heavyweight tools for the
 ad-hoc SSH tasks that come up in day-to-day server work.
 
-- **Project health:** CI runs on every PR, Python 3.9+ is supported, and the
+- **Project health:** CI runs on every PR, Python 3.10+ is supported, and the
   public API is versioned under [semantic versioning](https://semver.org/).
 - **Your code, your servers:** usage stays open under the MIT license — nothing
   is telemetry-driven or locked behind a service.

{remote_cmd_manager-2.3.0 → remote_cmd_manager-2.5.0}/pyproject.toml

@@ -7,7 +7,7 @@ name = "remote_cmd_manager"
 dynamic = ["version"]
 description = "Cross-platform SSH remote server management tool (Linux/macOS/Windows) — lightweight, zero-configuration CLI and Python API for managing servers over SSH. Supports host CRUD, batch commands, file transfer, credential encryption, async execution, and more."
 readme = "README.md"
-requires-python = ">=3.9"
+requires-python = ">=3.10"
 license = { text = "MIT" }
 authors = [
     { name = "Vae-Scrooge", email = "vaescrooge@gmail.com" },
@@ -19,7 +19,6 @@ classifiers = [
     "Intended Audience :: System Administrators",
     "License :: OSI Approved :: MIT License",
     "Programming Language :: Python :: 3",
-    "Programming Language :: Python :: 3.9",
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
@@ -33,7 +32,7 @@ classifiers = [
     "Operating System :: Microsoft :: Windows",
 ]
 dependencies = [
-    "paramiko>=3.0",
+    "paramiko>=5.0,<6",
     "click>=8.0",
     "cryptography>=41.0",
     "rich>=13.0",
@@ -43,22 +42,24 @@ dependencies = [
 
 [project.optional-dependencies]
 # 异步原生执行内核：启用 BatchExecutor(use_async=True) / AsyncSSHClient / AsyncConnectionPool 时需要
-async = ["asyncssh>=2.14.0"]
+# 下限锁定在 2.24.x：2.23.x 及更早版本存在 2026 年公开 CVE（SCP 路径穿越等）。
+async = ["asyncssh>=2.24.0,<3"]
 # 云平台主机发现（Phase 4 预留）
 cloud = ["boto3>=1.34"]
 # 开发与测试
+# 包含 async extra：默认测试套件会 import 异步模块，仅装 dev 无法收集。
 dev = [
     "pytest>=8.0",
     "pytest-asyncio>=0.23",
     "pytest-cov>=4.0",
     "ruff>=0.4",
     "mypy>=1.10",
+    "asyncssh>=2.24.0,<3",
     # 测试 keyring 凭据提供者（生产为可选依赖，测试环境固定安装）
     "keyring>=24.0",
 ]
-# 文档生成（pdoc>=16 需 Python>=3.10，固定到 15.x 以兼容 requires-python>=3.9）。
-# 精确 pin 15.0.4：pdoc HTML 输出随版本/解释器变化，docs/api 漂移门禁
-# （scripts/check_docs_drift.py）要求生成结果可复现。
+# 文档生成。pdoc 固定到 15.0.4：docs/api 漂移门禁（scripts/check_docs_drift.py）
+# 要求生成结果可复现。
 docs = ["pdoc==15.0.4"]
 
 [project.urls]
@@ -88,7 +89,7 @@ markers = [
 ]
 
 [tool.ruff]
-target-version = "py39"
+target-version = "py310"
 line-length = 100
 
 [tool.ruff.lint]
@@ -109,6 +110,12 @@ ignore = [
     "N812",
     "N999",
     "B904",
+    # PEP 604 / 新式导入重写推迟到 v2.6（保持 v2.5 变更面最小）
+    "UP006", # dict/list 泛型重写
+    "UP007", # Union -> X|Y
+    "UP035", # typing.* 导入重写
+    "UP041", # IOError -> TimeoutError 别名
+    "UP045", # Optional -> X|None
 ]
 
 [tool.ruff.lint.per-file-ignores]

{remote_cmd_manager-2.3.0 → remote_cmd_manager-2.5.0}/remote_cmd/__init__.py

@@ -48,7 +48,7 @@ Remote CMD - SSH 远程服务器管理工具
     - 文档: 参见 docs/ 目录
 
 Author: Vae-Scrooge
-Version: 2.3.0（单一真相源见 remote_cmd._version）
+Version: 2.5.0（单一真相源见 remote_cmd._version）
 License: MIT
 """
 
@@ -96,10 +96,16 @@ from remote_cmd.service import (
     HostService,
     SSHService,
 )
-from remote_cmd.service.batch_executor import BatchExecutor, BatchHostResult, BatchResult
+from remote_cmd.service.batch_executor import (
+    BatchExecutor,
+    BatchHostResult,
+    BatchResult,
+    OutputPolicy,
+)
 from remote_cmd.service.credential_provider import KeyringCredentialProvider
 from remote_cmd.service.task_runner import Task, TaskRunner, TaskStatus
 from remote_cmd.utils.crypto import CredentialEncryption
+from remote_cmd.utils.exceptions import PlaintextCredentialWarning
 from remote_cmd.utils.logging_utils import (
     SensitiveDataFilter,
     get_logger,
@@ -134,6 +140,8 @@ if _HAS_ASYNC:
         "BatchExecutor",
         "BatchResult",
         "BatchHostResult",
+        "OutputPolicy",
+        "PlaintextCredentialWarning",
         "SyncConnectionPool",
         "TaskRunner",
         "Task",
@@ -167,6 +175,8 @@ else:
         "BatchExecutor",
         "BatchResult",
         "BatchHostResult",
+        "OutputPolicy",
+        "PlaintextCredentialWarning",
         "SyncConnectionPool",
         "TaskRunner",
         "Task",

{remote_cmd_manager-2.3.0 → remote_cmd_manager-2.5.0}/remote_cmd/_version.py

@@ -9,4 +9,4 @@
 - ``__version__`` 由 ``remote_cmd/__init__.py`` 导入并继续作为公共 API 导出。
 """
 
-__version__ = "2.3.0"
+__version__ = "2.5.0"

{remote_cmd_manager-2.3.0 → remote_cmd_manager-2.5.0}/remote_cmd/repository/json_host_repository.py

@@ -4,8 +4,14 @@ JSON 文件主机仓库实现
 使用 JSON 文件存储主机配置，支持：
 - 原子写入（先写临时文件再重命名，防止崩溃导致数据丢失）
 - 可选加密（通过 CredentialEncryption 加密 password 字段）
+- 明文持久化策略（v2.5）
 - config version management
 - 自动从旧版本迁移
+
+并发语义（single-writer）：
+- 本实现面向**单进程/单写入者**"; 多进程并发写同一 JSON 文件
+  可能丢失更新（读-改-写无跨进程锁）。需要多进程/多写入者时，
+  请使用 SqliteHostRepository（WAL + busy_timeout 处理并发写）。
 """
 
 import builtins
@@ -14,13 +20,15 @@ import json
 import logging
 import os
 import tempfile
+import warnings
 from pathlib import Path
 from typing import Optional
 
 from remote_cmd.core.host import Host
 from remote_cmd.repository.host_repository import HostRepository
-from remote_cmd.utils.credential_guard import PasswordGuard
+from remote_cmd.utils.credential_guard import PasswordGuard, is_plaintext_password
 from remote_cmd.utils.crypto import CredentialEncryption
+from remote_cmd.utils.exceptions import CredentialError, PlaintextCredentialWarning
 
 logger = logging.getLogger(__name__)
 
@@ -36,6 +44,16 @@ class JsonHostRepository(HostRepository):
         filepath: JSON 文件路径
         encryption: 可选的凭据加密器（设置后自动加密 password）
         auto_load: 初始化时是否自动加载已有文件（默认 True）
+        allow_plaintext_credentials: 明文密码持久化策略（v2.5；默认 None
+            为兼容模式）。三态：
+            - None：允许，但在 flush 会持久化明文密码时发出
+              PlaintextCredentialWarning（兼容 v2.4 及更早）
+            - True：显式允许明文落盘（不再告警）
+            - False：flush 遇到明文密码时抛出 CredentialError
+            v3.0 起默认值计划切换为 False。
+
+    并发语义：单进程/单写入者（见模块 docstring）；多进程场景请使用
+    SqliteHostRepository。
     """
 
     def __init__(
@@ -43,10 +61,12 @@ class JsonHostRepository(HostRepository):
         filepath: str,
         encryption: Optional[CredentialEncryption] = None,
         auto_load: bool = True,
+        allow_plaintext_credentials: Optional[bool] = None,
     ) -> None:
         self._filepath = Path(filepath)
         self._encryption = encryption
         self._guard = PasswordGuard(encryption)
+        self._allow_plaintext = allow_plaintext_credentials
         self._hosts: dict[str, Host] = {}
 
         if auto_load and self._filepath.exists():
@@ -100,7 +120,14 @@ class JsonHostRepository(HostRepository):
     # ========================================================================
 
     def flush(self) -> None:
-        """原子写入 JSON 文件"""
+        """原子写入 JSON 文件
+
+        注意：JSON 持久化是单进程/单写入者语义，多进程并发写同一文件
+        可能丢失更新（无跨进程锁）；多进程场景请使用 SqliteHostRepository。
+
+        Raises:
+            CredentialError: allow_plaintext_credentials=False 且存在明文密码
+        """
         data = self._serialize_hosts()
         self._atomic_write(data)
 
@@ -112,12 +139,44 @@ class JsonHostRepository(HostRepository):
         if self._guard.enabled:
             for host_data in hosts_dict.values():
                 host_data["password"] = self._guard.encrypt(host_data.get("password"))
+        else:
+            self._enforce_plaintext_policy(hosts_dict)
 
         return {
             "version": CONFIG_VERSION,
             "hosts": hosts_dict,
         }
 
+    def _enforce_plaintext_policy(self, hosts_dict: dict) -> None:
+        """执行明文密码持久化策略（未配置加密器时）。
+
+        集合所有违规主机，一次 flush 最多发出一次警告或抛出一次异常。
+        """
+        if self._allow_plaintext is True:
+            return
+        offenders = [
+            name
+            for name, data in hosts_dict.items()
+            if is_plaintext_password(data.get("password"))
+        ]
+        if not offenders:
+            return
+        if self._allow_plaintext is False:
+            raise CredentialError(
+                "refusing to persist plaintext credentials for hosts: "
+                f"{', '.join(sorted(offenders))}. "
+                "Pass encryption=... to encrypt at rest, or set "
+                "allow_plaintext_credentials=True to explicitly opt in."
+            )
+        warnings.warn(
+            f"Plaintext credentials will be persisted for {len(offenders)} host(s): "
+            f"{', '.join(sorted(offenders))}. Pass encryption=... to encrypt at rest, or "
+            "allow_plaintext_credentials=True to suppress this warning "
+            "(v3.0 will reject plaintext persistence by default).",
+            PlaintextCredentialWarning,
+            stacklevel=4,
+        )
+
     def _load(self) -> None:
         """从 JSON 文件加载主机配置"""
         try:

{remote_cmd_manager-2.3.0 → remote_cmd_manager-2.5.0}/remote_cmd/repository/sqlite_host_repository.py

@@ -22,12 +22,14 @@ import logging
 import sqlite3
 import threading
 import time
+import warnings
 from typing import Optional
 
 from remote_cmd.core.host import Host
 from remote_cmd.repository.host_repository import HostRepository
-from remote_cmd.utils.credential_guard import PasswordGuard
+from remote_cmd.utils.credential_guard import PasswordGuard, is_plaintext_password
 from remote_cmd.utils.crypto import CredentialEncryption
+from remote_cmd.utils.exceptions import CredentialError, PlaintextCredentialWarning
 
 logger = logging.getLogger(__name__)
 
@@ -79,9 +81,19 @@ class SqliteHostRepository(HostRepository):
         auto_create: 是否自动创建表和数据库，默认 True
         encryption: 可选的凭据加密器（设置后 save() 自动加密 password）
         busy_timeout_ms: 写锁等待上限（毫秒），默认 5000
+        allow_plaintext_credentials: 明文密码持久化策略（v2.5；默认 None
+            为兼容模式）。三态：
+            - None：允许，但 save() 将要持久化明文密码时发出
+              PlaintextCredentialWarning（兼容 v2.4 及更早）
+            - True：显式允许明文落盘（不再告警）
+            - False：save() 遇到明文密码时抛出 CredentialError
+            v3.0 起默认值计划切换为 False。
 
     注意: 密码的加密依赖传入 encryption。若直接以明文密码调用 save()
     且未提供 encryption，明文会被持久化到数据库。请勿绕过 HostService。
+
+    并发：WAL + busy_timeout 处理多进程并发写，适合作为多写入者后端
+    （与 JsonHostRepository 的 single-writer 语义不同）。
     """
 
     def __init__(
@@ -91,12 +103,14 @@ class SqliteHostRepository(HostRepository):
         auto_create: bool = True,
         encryption: Optional[CredentialEncryption] = None,
         busy_timeout_ms: int = DEFAULT_BUSY_TIMEOUT_MS,
+        allow_plaintext_credentials: Optional[bool] = None,
     ) -> None:
         self._db_path = db_path
         self._lock = threading.Lock()
         self._encryption = encryption
         self._guard = PasswordGuard(encryption)
         self._busy_timeout_ms = busy_timeout_ms
+        self._allow_plaintext = allow_plaintext_credentials
 
         if auto_create:
             self._init_db()
@@ -246,7 +260,13 @@ class SqliteHostRepository(HostRepository):
     # ========================================================================
 
     def save(self, host: Host) -> None:
-        """保存或更新主机"""
+        """保存或更新主机
+
+        Raises:
+            CredentialError: allow_plaintext_credentials=False 且密码为明文
+        """
+        if not self._guard.enabled:
+            self._enforce_plaintext_policy(host.name, host.password)
         with self._lock, self._txn(write=True) as conn:
             tags_json = json.dumps(host.tags or [], ensure_ascii=False)
             # 配置了加密器时，明文密码先加密再落库
@@ -289,6 +309,27 @@ class SqliteHostRepository(HostRepository):
 
         return self._row_to_host(row)
 
+    def _enforce_plaintext_policy(self, name: str, password: Optional[str]) -> None:
+        """执行明文密码持久化策略（未配置加密器时）。"""
+        if self._allow_plaintext is True:
+            return
+        if not is_plaintext_password(password):
+            return
+        if self._allow_plaintext is False:
+            raise CredentialError(
+                f"refusing to persist plaintext credential for host '{name}'. "
+                "Pass encryption=... to encrypt at rest, or set "
+                "allow_plaintext_credentials=True to explicitly opt in."
+            )
+        warnings.warn(
+            f"Plaintext credential will be persisted for host '{name}'. "
+            "Pass encryption=... to encrypt at rest, or "
+            "allow_plaintext_credentials=True to suppress this warning "
+            "(v3.0 will reject plaintext persistence by default).",
+            PlaintextCredentialWarning,
+            stacklevel=4,
+        )
+
     def delete(self, name: str) -> None:
         """按名称删除主机"""
         with self._lock, self._txn(write=True) as conn: