vmware-storage 2.3.0__tar.gz → 2.3.1__tar.gz

{vmware_storage-2.3.0 → vmware_storage-2.3.1}/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "$schema": "https://anthropic.com/claude-code/plugin.schema.json",
   "name": "vmware-storage",
   "displayName": "VMware Storage",
-  "version": "2.3.0",
+  "version": "2.3.1",
   "description": "VMware vSphere storage with 15 MCP tools: datastores, iSCSI, vSAN, FC multipath.",
   "author": {
     "name": "Wei Zhou",

{vmware_storage-2.3.0 → vmware_storage-2.3.1}/.mcp.json

@@ -5,7 +5,7 @@
       "command": "uvx",
       "args": [
         "--from",
-        "vmware-storage==2.3.0",
+        "vmware-storage==2.3.1",
         "vmware-storage-mcp"
       ]
     }

{vmware_storage-2.3.0 → vmware_storage-2.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: vmware-storage
-Version: 2.3.0
+Version: 2.3.1
 Summary: VMware vSphere storage management: datastores, iSCSI, vSAN. Domain-focused MCP skill.
 Project-URL: Homepage, https://github.com/vmware-skills/VMware-Storage
 Project-URL: Repository, https://github.com/vmware-skills/VMware-Storage
@@ -16,7 +16,7 @@ Requires-Dist: python-dotenv<2.0,>=1.0
 Requires-Dist: pyvmomi<10.0,>=8.0.3.0
 Requires-Dist: rich<15.0,>=13.0
 Requires-Dist: typer<1.0,>=0.12
-Requires-Dist: vmware-policy<2.0,>=1.22.0
+Requires-Dist: vmware-policy<2.0,>=1.23.0
 Description-Content-Type: text/markdown
 
 <!-- mcp-name: io.github.vmware-skills/vmware-storage -->
@@ -276,6 +276,7 @@ vmware-storage-mcp
 | `get_vsan_health` returns `overall_health: null` | `null` = not asked (see `health_not_queried_reason`), never a measurement; a string is always vSAN's own answer, including its own `"unknown"`. Usual cause: connected to standalone ESXi, but the health service runs in **vCenter**. |
 | Rescan doesn't discover new LUNs | Wait 15-30 seconds after adding targets, then rescan again. Verify target IP is reachable from ESXi. |
 | "Password not found" error | Variable names follow `VMWARE_<TARGET_UPPER>_PASSWORD` (hyphens → underscores). Check `~/.vmware-storage/.env`. |
+| `doctor` fails with "no vSphere role", or every command fails with "session is not authenticated" | The login works but the account has no vSphere role. Assign one (Read-Only or higher) on the vCenter root folder (Administration > Access Control > Global Permissions). Mid-run, the same fault can be an expired session: run the command again. |
 | Connection timeout to vCenter | Use `vmware-storage doctor --skip-auth` to bypass auth checks on high-latency networks. |
 | "Datastore browse did not finish within Ns" | The datastore is very large or busy. Narrow the search with a sub-path and a specific pattern (e.g. `datastore browse ds01 --path templates --pattern "*.ova"`) instead of browsing the root — do not just retry the same broad browse. |
 
@@ -319,6 +320,12 @@ claude mcp add --transport http vmware-storage https://mcp.example.com:8443/mcp
   before it binds that unauthenticated requests get 401. Use a certificate your clients trust for those names.
 - Behind a TLS-terminating reverse proxy on the same machine use `--transport http --host 127.0.0.1
   --public-name mcp.example.com` and pass the `Authorization` header through.
+- Behind a load balancer or gateway on another machine, keep `--transport https` (a self-signed certificate is
+  fine), list in `--public-name` the host name the balancer sends as `Host`, and have it forward `Authorization`.
+  Its health probe can use `GET /healthz`, which needs no token and returns only `{"status": "ok"}`
+  (vmware-policy ≥ 1.23.0).
+- Send `traceparent` or `X-Request-ID` with each request to have it stored on the audit row;
+  `vmware-audit log --correlation-id ID` then finds the calls behind one platform request.
 - The audit log records each caller as `token:<name>`. Calls run side by side, also on the same target: the server keeps up to `VMWARE_MCP_POOL_SIZE` (default 2) sessions per target, each one a login on that target, and a call waits at most 300 s for a free session (vmware-policy ≥ 1.22.0).
 - **Everyone who can reach the endpoint acts with this server's account.** Tokens identify callers; they grant
   nothing on the platform. Run one endpoint per privilege level. `vmware-storage access-info` shows which account that is and what it may do.

{vmware_storage-2.3.0 → vmware_storage-2.3.1}/README-CN.md

@@ -290,6 +290,7 @@ vmware-storage-mcp
 | `get_vsan_health` 返回 `overall_health: null` | `null` 表示**没有查询**（原因见 `health_not_queried_reason`），不是测量结果；只要是字符串就一定是 vSAN 自己给的答案，包括它自己的 `"unknown"`。常见原因：连的是独立 ESXi，而健康服务跑在 **vCenter** 上。 |
 | 重扫后未发现新 LUN | 添加目标后等待 15-30 秒再重扫。确认 ESXi 能访问目标 IP。 |
 | "Password not found" 错误 | 变量名规则：`VMWARE_<目标名大写>_PASSWORD`（连字符→下划线）。检查 `~/.vmware-storage/.env`。 |
+| `doctor` 报 "no vSphere role"，或每个命令都报 "session is not authenticated" | 能登录，但账号没有 vSphere 角色。在 vCenter 根文件夹上给它分配一个角色（Read-Only 或更高）：Administration > Access Control > Global Permissions。运行中出现同一错误也可能是会话过期：重跑命令即可。 |
 | 连接 vCenter 超时 | 使用 `vmware-storage doctor --skip-auth` 跳过高延迟网络的认证检查。 |
 
 <!-- usage: remote-and-exposure -->
@@ -332,6 +333,11 @@ claude mcp add --transport http vmware-storage https://mcp.example.com:8443/mcp
   证书要用客户端信任、且覆盖这些名字的证书。
 - 在同一台机器上由反向代理终结 TLS 时，用 `--transport http --host 127.0.0.1 --public-name mcp.example.com`，
   并让代理透传 `Authorization` 头。
+- 负载均衡或网关在另一台机器上时，保持 `--transport https`（自签证书也可以），在 `--public-name` 里写上负载均衡
+  转发时带的 `Host` 名，并让它透传 `Authorization`。健康检查可以用 `GET /healthz`：不需要 token，只返回
+  `{"status": "ok"}`（需 vmware-policy ≥ 1.23.0）。
+- 每个请求带上 `traceparent` 或 `X-Request-ID`，它会记进审计记录；用 `vmware-audit log --correlation-id ID`
+  就能查到平台上某一次请求对应的调用。
 - 审计日志把每个调用者记为 `token:<名字>`。调用并行执行，同一 target 上也一样：server 为每个 target 最多保持 `VMWARE_MCP_POOL_SIZE`（默认 2）个会话，每个会话都是在该 target 上的一次登录；一个调用最多等 300 秒拿到空闲会话（vmware-policy ≥ 1.22.0）。
 - **能连到这个端点的人，都以该 server 配置的账号操作。** token 只用来识别调用者，不在平台上授予任何权限。
   每个权限级别单独起一个端点。`vmware-storage access-info` 可查看是哪个账号、它能做什么。

{vmware_storage-2.3.0 → vmware_storage-2.3.1}/README.md

@@ -255,6 +255,7 @@ vmware-storage-mcp
 | `get_vsan_health` returns `overall_health: null` | `null` = not asked (see `health_not_queried_reason`), never a measurement; a string is always vSAN's own answer, including its own `"unknown"`. Usual cause: connected to standalone ESXi, but the health service runs in **vCenter**. |
 | Rescan doesn't discover new LUNs | Wait 15-30 seconds after adding targets, then rescan again. Verify target IP is reachable from ESXi. |
 | "Password not found" error | Variable names follow `VMWARE_<TARGET_UPPER>_PASSWORD` (hyphens → underscores). Check `~/.vmware-storage/.env`. |
+| `doctor` fails with "no vSphere role", or every command fails with "session is not authenticated" | The login works but the account has no vSphere role. Assign one (Read-Only or higher) on the vCenter root folder (Administration > Access Control > Global Permissions). Mid-run, the same fault can be an expired session: run the command again. |
 | Connection timeout to vCenter | Use `vmware-storage doctor --skip-auth` to bypass auth checks on high-latency networks. |
 | "Datastore browse did not finish within Ns" | The datastore is very large or busy. Narrow the search with a sub-path and a specific pattern (e.g. `datastore browse ds01 --path templates --pattern "*.ova"`) instead of browsing the root — do not just retry the same broad browse. |
 
@@ -298,6 +299,12 @@ claude mcp add --transport http vmware-storage https://mcp.example.com:8443/mcp
   before it binds that unauthenticated requests get 401. Use a certificate your clients trust for those names.
 - Behind a TLS-terminating reverse proxy on the same machine use `--transport http --host 127.0.0.1
   --public-name mcp.example.com` and pass the `Authorization` header through.
+- Behind a load balancer or gateway on another machine, keep `--transport https` (a self-signed certificate is
+  fine), list in `--public-name` the host name the balancer sends as `Host`, and have it forward `Authorization`.
+  Its health probe can use `GET /healthz`, which needs no token and returns only `{"status": "ok"}`
+  (vmware-policy ≥ 1.23.0).
+- Send `traceparent` or `X-Request-ID` with each request to have it stored on the audit row;
+  `vmware-audit log --correlation-id ID` then finds the calls behind one platform request.
 - The audit log records each caller as `token:<name>`. Calls run side by side, also on the same target: the server keeps up to `VMWARE_MCP_POOL_SIZE` (default 2) sessions per target, each one a login on that target, and a call waits at most 300 s for a free session (vmware-policy ≥ 1.22.0).
 - **Everyone who can reach the endpoint acts with this server's account.** Tokens identify callers; they grant
   nothing on the platform. Run one endpoint per privilege level. `vmware-storage access-info` shows which account that is and what it may do.

{vmware_storage-2.3.0 → vmware_storage-2.3.1}/RELEASE_NOTES.md

@@ -1,3 +1,18 @@
+## v2.3.1 — a login with no vSphere role is named as such (AIops#47)
+
+* An account that logs in but has no vSphere role (vCenter shows no session for it) is now refused at connect time
+  with a message naming the missing role (assign Read-Only or higher), on the `doctor` auth row, the CLI and every
+  MCP tool. The session is logged out and never cached. Before, `doctor` passed and every call then failed with
+  "the session is not authenticated".
+* Refused only when two signals agree: no session, **and** vCenter refuses a view of the root folder
+  (`NotAuthenticated` / `NoPermission`). An account scoped to one folder can also show no session, and still
+  connects; anything the check cannot read lets the login through.
+* The MCP hint beside these two errors (tool errors and `get_access_info`) points at `doctor`'s role check
+  instead of "verify connectivity".
+* `NotAuthenticated` raised later (session expired, or a role removed while running) now says both causes, on the
+  CLI (it was a raw traceback) and over MCP (it was `NotAuthenticated: operation failed.`).
+* Requires vmware-policy 1.23.0.
+
 ## v2.3.0 — calls run side by side on one target; `get_access_info`
 
 **Concurrent calls (HLD §16 D-13(2), issue #18).** On a shared HTTPS server, calls no longer wait for each other:

{vmware_storage-2.3.0 → vmware_storage-2.3.1}/openclaw.plugin.json

@@ -11,7 +11,7 @@
       "command": "uvx",
       "args": [
         "--from",
-        "vmware-storage==2.3.0",
+        "vmware-storage==2.3.1",
         "vmware-storage-mcp"
       ]
     }

{vmware_storage-2.3.0 → vmware_storage-2.3.1}/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zw008/vmware-storage",
-  "version": "2.3.0",
+  "version": "2.3.1",
   "description": "VMware vSphere storage with 15 MCP tools: datastores, iSCSI, vSAN, FC multipath.",
   "private": true,
   "license": "MIT",

{vmware_storage-2.3.0 → vmware_storage-2.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "vmware-storage"
-version = "2.3.0"
+version = "2.3.1"
 description = "VMware vSphere storage management: datastores, iSCSI, vSAN. Domain-focused MCP skill."
 readme = "README.md"
 license = "MIT"
@@ -17,7 +17,7 @@ dependencies = [
     "rich>=13.0,<15.0",
     "python-dotenv>=1.0,<2.0",
     "mcp[cli]>=1.28,<2.0",
-    "vmware-policy>=1.22.0,<2.0",
+    "vmware-policy>=1.23.0,<2.0",
 ]
 
 

{vmware_storage-2.3.0 → vmware_storage-2.3.1}/server.json

@@ -7,12 +7,12 @@
     "url": "https://github.com/vmware-skills/VMware-Storage",
     "source": "github"
   },
-  "version": "2.3.0",
+  "version": "2.3.1",
   "packages": [
     {
       "registryType": "pypi",
       "identifier": "vmware-storage",
-      "version": "2.3.0",
+      "version": "2.3.1",
       "runtimeHint": "uvx",
       "packageArguments": [
         {

{vmware_storage-2.3.0 → vmware_storage-2.3.1}/skills/vmware-storage/SKILL.md

@@ -40,7 +40,7 @@ VMware vSphere storage management — 15 MCP tools for datastores, iSCSI, vSAN,
 ## Quick Install
 
 ```bash
-uv tool install vmware-storage==2.3.0
+uv tool install vmware-storage==2.3.1
 vmware-storage init      # guided setup: writes config + .env (chmod 600, password grep-safe), then verifies
 vmware-storage doctor
 ```
@@ -234,6 +234,10 @@ After adding iSCSI targets, the storage subsystem may need 10-30 seconds to enum
 
 The password environment variable is missing. Variable names follow the pattern `VMWARE_<TARGET_NAME_UPPER>_PASSWORD` where hyphens become underscores. Example: target `my-vcenter` needs `VMWARE_MY_VCENTER_PASSWORD`. Check your `~/.vmware-storage/.env` file.
 
+### "Session is not authenticated" or "no vSphere role" right after login
+
+The password is right; the account has no vSphere role, so vCenter shows no session for it and every call fails. `doctor` now reports this on the auth row. Assign the account a role (Read-Only or higher) on the vCenter root folder under Administration > Access Control > Global Permissions. Seen mid-run, the same fault can also be an expired session: run the command again.
+
 ### Doctor reports ".env permissions too open"
 
 The `.env` file contains passwords and must have owner-only permissions:
@@ -267,7 +271,7 @@ Corporate TLS proxies inject certificates that uv's bundled CA store doesn't tru
 ## Setup
 
 ```bash
-uv tool install vmware-storage==2.3.0
+uv tool install vmware-storage==2.3.1
 mkdir -p ~/.vmware-storage
 cp config.example.yaml ~/.vmware-storage/config.yaml
 # Edit config.yaml with your vCenter/ESXi targets

{vmware_storage-2.3.0 → vmware_storage-2.3.1}/skills/vmware-storage/references/setup-guide.md

@@ -13,19 +13,19 @@ Complete setup and security guide for `vmware-storage`.
 ### Via uv (recommended)
 
 ```bash
-uv tool install vmware-storage==2.3.0
+uv tool install vmware-storage==2.3.1
 ```
 
 ### Via pip
 
 ```bash
-pip install vmware-storage==2.3.0
+pip install vmware-storage==2.3.1
 ```
 
 ### From source
 
 ```bash
-git clone --branch v2.3.0 https://github.com/vmware-skills/VMware-Storage.git
+git clone --branch v2.3.1 https://github.com/vmware-skills/VMware-Storage.git
 cd VMware-Storage
 pip install -e .
 ```
@@ -235,6 +235,13 @@ vmware-storage mcp --transport https --host 0.0.0.0 --port 8443 \
 - Behind a reverse proxy that terminates TLS (Nginx, HAProxy) on the same machine, use
   `--transport http --host 127.0.0.1 --public-name mcp.example.com` (the names the proxy forwards in `Host`), and
   have the proxy pass the `Authorization` header through.
+- Behind a load balancer or gateway on another machine, keep `--transport https` (a self-signed certificate is
+  fine: the balancer is the client that has to trust it), list in `--public-name` the host name the balancer sends
+  as `Host`, and have it forward `Authorization`. Point its health probe at `GET /healthz`: it needs no token, returns
+  only `{"status": "ok"}` and accepts any `Host` (vmware-policy ≥ 1.23.0). Every other path still needs the token.
+- Correlation: each audit row stores the caller's `traceparent` trace-id, else its `X-Request-ID` /
+  `X-Correlation-ID`. Have the agent platform send one, and `vmware-audit log --correlation-id ID` lists the calls
+  behind one platform request.
 - `vmware-audit token list` / `token revoke NAME` manage callers; a revoked token is refused from its next request.
   Replace a leaked token under a new name.
 - The server will not start without at least one token, and checks before it binds that unauthenticated requests

{vmware_storage-2.3.0 → vmware_storage-2.3.1}/tests/eval/regression/test_atexit_handlers_do_not_accumulate.py

@@ -43,9 +43,15 @@ def _target(name: str = "vcenter-prod") -> TargetConfig:
     return TargetConfig(name=name, host="vc.example.com", config_username="svc")
 
 
-def _dead_si(*_a, **_kw):
-    """An SI whose liveness probe says dead, so the next connect() evicts it."""
+def _live_si(*_a, **_kw):
+    """An SI with a session; a login without one is refused (AIops#47)."""
     si = MagicMock()
+    si.content.sessionManager.currentSession = MagicMock()
+    return si
+
+
+def _expire(si: MagicMock) -> MagicMock:
+    """The session expires after login, so the next connect() evicts it."""
     si.content.sessionManager.currentSession = None
     return si
 
@@ -53,7 +59,7 @@ def _dead_si(*_a, **_kw):
 @pytest.mark.unit
 def test_a_released_connection_is_collectable() -> None:
     """The mechanism: what connect() registers, _release_si takes back."""
-    with patch("pyVim.connect.SmartConnect", side_effect=_dead_si):
+    with patch("pyVim.connect.SmartConnect", side_effect=_live_si):
         si = ConnectionManager._create_connection(_target())
     ref = weakref.ref(si)
 
@@ -68,7 +74,7 @@ def test_a_connection_not_released_is_pinned() -> None:
     """The negative half. Without this, the test above could pass because
     nothing ever held the object -- and would then keep passing with the whole
     registration deleted."""
-    with patch("pyVim.connect.SmartConnect", side_effect=_dead_si):
+    with patch("pyVim.connect.SmartConnect", side_effect=_live_si):
         si = ConnectionManager._create_connection(_target())
     ref = weakref.ref(si)
 
@@ -87,10 +93,10 @@ def test_repeated_eviction_does_not_pin_every_session() -> None:
     mgr = ConnectionManager(cfg)
 
     seen: list[weakref.ref] = []
-    with patch("pyVim.connect.SmartConnect", side_effect=_dead_si), \
+    with patch("pyVim.connect.SmartConnect", side_effect=_live_si), \
          patch("pyVim.connect.Disconnect"):
         for _ in range(20):
-            seen.append(weakref.ref(mgr.connect("vcenter-prod")))
+            seen.append(weakref.ref(_expire(mgr.connect("vcenter-prod"))))
         # Drop the last, still-cached session the way production does.
         mgr.disconnect_all()
     gc.collect()

vmware_storage-2.3.1/tests/eval/regression/test_login_without_a_role.py

@@ -0,0 +1,215 @@
+"""A login that works but has no vSphere role (AIops#47).
+
+Reported on vCenter 8.0.3: an account with no vSphere role logs in, vCenter
+shows no session for it (``currentSession`` is ``None``), and every inventory
+call then fails with ``vim.fault.NotAuthenticated``. ``doctor`` passed, and the
+error told the user to check credentials, which were fine.
+
+Driven through the real ConnectionManager, doctor, CLI handler and MCP tool;
+only ``SmartConnect`` / ``Disconnect`` are fakes, so nothing touches a network.
+"""
+
+from __future__ import annotations
+
+from unittest.mock import MagicMock, patch
+
+import pytest
+import typer
+from pyVmomi import vim
+
+from vmware_storage import doctor
+from vmware_storage.config import AppConfig, TargetConfig
+from vmware_storage.connection import _SI_ATEXIT, ConnectionManager, NoVsphereRoleError
+from vmware_storage.mcp_server import server
+
+ROLE_WORDS = ("no vSphere role", "Read-Only")
+
+
+def _config() -> AppConfig:
+    return AppConfig(
+        targets=(
+            TargetConfig(name="lab", host="vc.example.com", config_username="u@vsphere.local"),
+        )
+    )
+
+
+def _si(has_session: bool, *, root_readable: bool = False) -> MagicMock:
+    """A login as vCenter answers it.
+
+    No role (AIops#47) takes both signals: ``currentSession`` reads ``None`` and
+    a container view on the root folder is refused with NotAuthenticated.
+    ``root_readable`` is the scoped account (one folder, or Supervisor namespace
+    permissions only): no session either, but the root view opens.
+    """
+    si = MagicMock(name="si")
+    si.content.sessionManager.currentSession = MagicMock() if has_session else None
+    if not has_session and not root_readable:
+        si.content.viewManager.CreateContainerView.side_effect = vim.fault.NotAuthenticated()
+    return si
+
+
+@pytest.fixture
+def fake_login(monkeypatch):
+    monkeypatch.setenv("VMWARE_LAB_PASSWORD", "pw")
+
+    def install(has_session: bool, root_readable: bool = False):
+        si = _si(has_session, root_readable=root_readable)
+        return si, patch("pyVim.connect.SmartConnect", return_value=si), patch(
+            "pyVim.connect.Disconnect"
+        )
+
+    return install
+
+
+@pytest.mark.unit
+def test_role_less_login_is_refused_closed_and_not_cached(fake_login):
+    si, connect, disconnect = fake_login(has_session=False)
+    mgr = ConnectionManager(_config())
+    with connect as smart, disconnect as dis:
+        with pytest.raises(NoVsphereRoleError) as excinfo:
+            mgr.connect("lab")
+        msg = str(excinfo.value)
+        for word in ROLE_WORDS:
+            assert word in msg
+        assert "'lab'" in msg
+        dis.assert_called_once_with(si)  # the session is logged out
+        assert id(si) not in _SI_ATEXIT  # and its exit handler unpinned
+        assert mgr.list_connected() == []  # nothing cached
+        with pytest.raises(NoVsphereRoleError):
+            mgr.connect("lab")
+        assert smart.call_count == 2  # the second call logged in again
+
+
+@pytest.mark.unit
+def test_normal_login_is_unaffected(fake_login):
+    si, connect, disconnect = fake_login(has_session=True)
+    mgr = ConnectionManager(_config())
+    with connect, disconnect as dis:
+        assert mgr.connect("lab") is si
+        assert mgr.list_connected() == ["lab"]
+        dis.assert_not_called()
+        mgr.disconnect_all()
+
+
+@pytest.mark.unit
+def test_scoped_account_without_a_session_still_connects(fake_login):
+    """``currentSession`` alone is not a verdict: a readable root view lets it through."""
+    si, connect, disconnect = fake_login(has_session=False, root_readable=True)
+    mgr = ConnectionManager(_config())
+    with connect, disconnect as dis:
+        assert mgr.connect("lab") is si  # no NoVsphereRoleError
+        assert mgr.list_connected() == ["lab"]  # cached like any session
+        dis.assert_not_called()
+        view = si.content.viewManager.CreateContainerView.return_value
+        view.Destroy.assert_called_once_with()  # the probe leaves no view behind
+        mgr.disconnect_all()
+
+
+@pytest.mark.unit
+def test_doctor_auth_row_names_the_missing_role(fake_login, monkeypatch):
+    _, connect, disconnect = fake_login(has_session=False)
+    monkeypatch.setattr(type(doctor.resolve_config_path()), "exists", lambda self: True)
+    monkeypatch.setattr("vmware_storage.config.load_config", _config)
+    with connect, disconnect:
+        ok, row = doctor._check_auth()
+    assert ok is False
+    for word in ROLE_WORDS:
+        assert word in row
+
+
+@pytest.mark.unit
+def test_mcp_tool_returns_the_role_message_whole(fake_login, monkeypatch):
+    _, connect, disconnect = fake_login(has_session=False)
+    mgr = ConnectionManager(_config())
+    monkeypatch.setattr(server, "_get_conn_mgr", lambda: mgr)
+    with connect, disconnect:
+        out = server.list_all_datastores(target="lab")
+    for word in ROLE_WORDS:
+        assert word in out["error"]
+    # The remedy sits at the end of the message; the 300-character cap cut it.
+    assert "vmware-storage doctor" in out["error"]
+    # The hint points at the role check, not at connectivity, which is fine.
+    assert "session" in out["hint"] and "verify connectivity" not in out["hint"]
+
+
+@pytest.mark.unit
+def test_cli_handler_prints_the_role_message(fake_login, monkeypatch, capsys):
+    from vmware_storage import cli
+
+    _, connect, disconnect = fake_login(has_session=False)
+    monkeypatch.setattr(cli, "load_config", lambda path=None: _config())
+
+    @cli.handle_cli_errors
+    def run():
+        cli._get_connection("lab")
+
+    with connect, disconnect, pytest.raises(typer.Exit):
+        run()
+    out = " ".join(capsys.readouterr().out.split())
+    for word in ROLE_WORDS:
+        assert word in out
+
+
+# ── NotAuthenticated raised later: expired session, or a role removed ─────────
+
+
+def _says_both(text: str) -> None:
+    text = " ".join(text.split())
+    assert "expired" in text and "run the command again" in text
+    assert "no vSphere role" in text and "Read-Only" in text
+
+
+@pytest.mark.unit
+def test_cli_not_authenticated_says_both_causes(capsys):
+    from vmware_storage.cli import handle_cli_errors
+
+    @handle_cli_errors
+    def boom():
+        raise vim.fault.NotAuthenticated()
+
+    with pytest.raises(typer.Exit):
+        boom()
+    _says_both(capsys.readouterr().out)
+
+
+@pytest.mark.unit
+def test_mcp_not_authenticated_says_both_causes(monkeypatch):
+    def _boom(target=None):
+        raise vim.fault.NotAuthenticated()
+
+    monkeypatch.setattr(server, "_get_connection", _boom)
+    out = server.list_all_datastores(target="lab")
+    _says_both(out["error"])
+    assert "operation failed" not in out["error"]
+    assert "session" in out["hint"] and "verify connectivity" not in out["hint"]
+
+
+@pytest.mark.unit
+def test_get_access_info_hint_names_the_role_check(fake_login, monkeypatch):
+    _, connect, disconnect = fake_login(has_session=False)
+    mgr = ConnectionManager(_config())
+    monkeypatch.setattr(server, "_get_conn_mgr", lambda: mgr)
+    with connect, disconnect:
+        out = server.get_access_info(target="lab")
+    for word in ROLE_WORDS:
+        assert word in out["error"]
+    assert "session" in out["hint"] and "verify connectivity" not in out["hint"]
+
+
+@pytest.mark.unit
+def test_write_tool_error_reply_hint_names_the_role_check():
+    out = server._error_reply(vim.fault.NotAuthenticated(), "storage")
+    assert "session" in out["hint"] and "verify connectivity" not in out["hint"]
+    other = server._error_reply(TimeoutError("slow"), "storage")
+    assert "verify connectivity" in other["hint"]
+
+
+@pytest.mark.unit
+def test_doctor_row_is_not_a_class_name(fake_login, monkeypatch):
+    """The row must carry the text, not 'NoVsphereRoleError'."""
+    _, connect, disconnect = fake_login(has_session=False)
+    monkeypatch.setattr(type(doctor.resolve_config_path()), "exists", lambda self: True)
+    monkeypatch.setattr("vmware_storage.config.load_config", _config)
+    with connect, disconnect:
+        _, row = doctor._check_auth()
+    assert "NoVsphereRoleError" not in row

{vmware_storage-2.3.0 → vmware_storage-2.3.1}/uv.lock

@@ -1162,21 +1162,21 @@ wheels = [
 
 [[package]]
 name = "vmware-policy"
-version = "1.22.0"
+version = "1.23.0"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "pyyaml" },
     { name = "rich" },
     { name = "typer" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/d7/52/405a9d5e88d79649f4d7bddade8248f38ab6a508007a7500a3cdcf81897a/vmware_policy-1.22.0.tar.gz", hash = "sha256:e1a96b44ddf3c4d00fb8bdcaae4e1a059b03f343a84df9de23f865122d3dc280", size = 319890, upload-time = "2026-10-15T14:39:45.757Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/1b/ef/2c56cc93e0744d7e68b75f7a288f580215865b4685a07b9d58e49773819b/vmware_policy-1.23.0.tar.gz", hash = "sha256:70a682fa44e36fadee7ca09c7c5411fff51c9e25ad9d638f9877737361e2ae31", size = 325401, upload-time = "2026-10-16T00:10:32.297Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/73/b5/2536cc8750c3ecb0a57c573def664989642ccae1a4f4a8b4283e34877721/vmware_policy-1.22.0-py3-none-any.whl", hash = "sha256:ca8afc5731e926b5eb1b93e26e14763b477bd45c33d3808138fb72903e2af664", size = 108585, upload-time = "2026-10-15T14:39:43.888Z" },
+    { url = "https://files.pythonhosted.org/packages/e3/ca/bdfc9e50cedf6684ed7d34348177f7688323617ce26d492f55b3d80cd45c/vmware_policy-1.23.0-py3-none-any.whl", hash = "sha256:2f35a97f7d0997dd49ab5a0d8d0fd5f4eae11ef66ca8ed26bc9e4b395cb0d45c", size = 110836, upload-time = "2026-10-16T00:10:30.55Z" },
 ]
 
 [[package]]
 name = "vmware-storage"
-version = "2.3.0"
+version = "2.3.1"
 source = { editable = "." }
 dependencies = [
     { name = "mcp", extra = ["cli"] },
@@ -1203,7 +1203,7 @@ requires-dist = [
     { name = "pyvmomi", specifier = ">=8.0.3.0,<10.0" },
     { name = "rich", specifier = ">=13.0,<15.0" },
     { name = "typer", specifier = ">=0.12,<1.0" },
-    { name = "vmware-policy", specifier = ">=1.22.0,<2.0" },
+    { name = "vmware-policy", specifier = ">=1.23.0,<2.0" },
 ]
 
 [package.metadata.requires-dev]

{vmware_storage-2.3.0 → vmware_storage-2.3.1}/vmware_storage/__init__.py

@@ -1,3 +1,3 @@
 """VMware Storage — vSphere datastore, iSCSI, and vSAN management."""
 
-__version__ = "2.3.0"
+__version__ = "2.3.1"

{vmware_storage-2.3.0 → vmware_storage-2.3.1}/vmware_storage/cli.py

@@ -16,7 +16,7 @@ from rich.text import Text
 from vmware_policy import PolicyDenied, audited, cli_local, guarded
 
 from vmware_storage.config import load_config
-from vmware_storage.connection import ConnectionManager
+from vmware_storage.connection import NOT_AUTHENTICATED_HINT, ConnectionManager
 from vmware_storage.notify.audit import AuditLogger
 from vmware_storage.ops.datastore_browser import DatastoreBrowseError
 from vmware_storage.ops.iscsi_config import HostNotFoundError, ISCSIError
@@ -84,7 +84,7 @@ def _expected_error_types() -> tuple[type[BaseException], ...]:
     """Expected error types, including the lazily-imported SOAP auth fault."""
     from pyVmomi import vim
 
-    return (*_EXPECTED_ERRORS, vim.fault.InvalidLogin)
+    return (*_EXPECTED_ERRORS, vim.fault.InvalidLogin, vim.fault.NotAuthenticated)
 
 
 def handle_cli_errors(fn):
@@ -124,6 +124,10 @@ def handle_cli_errors(fn):
                     "VMWARE_<TARGET>_PASSWORD) and the username in "
                     "~/.vmware-storage/config.yaml. Re-run 'vmware-storage init' to reset both."
                 )
+            elif isinstance(e, vim.fault.NotAuthenticated):
+                # Not a credentials problem: the session expired, or the
+                # account has no vSphere role (AIops#47). Say both.
+                msg = NOT_AUTHENTICATED_HINT
             elif isinstance(e, ssl.SSLError):
                 # Self-signed lab certs are the usual cause; teach the toggle.
                 msg = (

{vmware_storage-2.3.0 → vmware_storage-2.3.1}/vmware_storage/connection.py

@@ -15,6 +15,7 @@ from pyVmomi import vim
 if TYPE_CHECKING:
     from pyVmomi.vim import ServiceInstance
 
+from vmware_policy.access import login_has_no_session, no_role_message
 from vmware_policy.pool import SessionPool
 
 from vmware_storage.config import CONFIG_FILE, AppConfig, ConfigError, TargetConfig, load_config
@@ -85,6 +86,23 @@ class ConnectError(ConfigError):
         self.cause_name = cause_name
 
 
+class NoVsphereRoleError(ConnectError):
+    """The login was accepted but the account has no vSphere role (AIops#47).
+
+    A dedicated class so every surface can tell it from a transport failure:
+    the message is authored (the target name from config.yaml, nothing from
+    the server) and names the missing role, not the password.
+    """
+
+
+NOT_AUTHENTICATED_HINT = (
+    "vCenter answered 'the session is not authenticated'. Either the session "
+    "expired (run the command again; a new session is opened) or the account "
+    "has no vSphere role (assign Read-Only or higher on the vCenter root folder, "
+    "then run 'vmware-storage doctor'). Changing the password will not help."
+)
+
+
 def _connect_failed(target: TargetConfig, exc: BaseException) -> ConnectError:
     """Authored replacement for a transport error, safe to show an agent.
 
@@ -243,6 +261,17 @@ class ConnectionManager:
 
         _SI_ATEXIT[id(si)] = _cleanup
         atexit.register(_cleanup)
+
+        # An account with no vSphere role logs in fine and then reads nothing:
+        # vCenter shows no session for it, a root-folder view is refused, and
+        # every call fails with NotAuthenticated (AIops#47). Just after login an expired session is
+        # not the explanation, so refuse here, where doctor sees it too, and
+        # close the session the way the pool would so nothing caches it.
+        if login_has_no_session(si):
+            _close_si(si)
+            raise NoVsphereRoleError(
+                no_role_message(target.name, "vmware-storage"), cause_name="NoVsphereRole"
+            )
         return si
 
 

{vmware_storage-2.3.0 → vmware_storage-2.3.1}/vmware_storage/mcp_server/server.py

@@ -41,7 +41,11 @@ from vmware_policy.access import unknown_tool_message, vsphere_access_info
 from vmware_storage import __version__
 from vmware_storage.access_requirements import REQUIREMENTS
 from vmware_storage.config import AppConfig, ConfigError, load_config
-from vmware_storage.connection import ConnectionManager
+from vmware_storage.connection import (
+    NOT_AUTHENTICATED_HINT,
+    ConnectionManager,
+    NoVsphereRoleError,
+)
 from vmware_storage.notify.audit import AuditLogger
 from vmware_storage.ops import datastore_browser
 from vmware_storage.ops import iscsi_config as _iscsi_config
@@ -116,6 +120,14 @@ def _safe_error(exc: Exception, tool: str) -> str:
     # reads the remedy for them from the CLI, which catches ssl.SSLError itself.
     if isinstance(exc, ssl.SSLError):
         return f"{type(exc).__name__}: operation failed."
+    # Both authored here, so nothing from the server travels. The role error is
+    # longer than the 300-character cap, and its remedy is at the end (AIops#47).
+    if isinstance(exc, NoVsphereRoleError):
+        return sanitize(str(exc), 500)
+    from pyVmomi import vim
+
+    if isinstance(exc, vim.fault.NotAuthenticated):
+        return NOT_AUTHENTICATED_HINT
     _passthrough = (
         ValueError,
         FileNotFoundError,
@@ -135,6 +147,22 @@ def _safe_error(exc: Exception, tool: str) -> str:
     return f"{type(exc).__name__}: operation failed."
 
 
+_DOCTOR_HINT = "Run 'vmware-storage doctor' to verify connectivity."
+#: For the two failures where connectivity and credentials are fine (AIops#47).
+_ROLE_HINT = (
+    "Run 'vmware-storage doctor': it checks every target's login and whether "
+    "vCenter gives the account a session."
+)
+
+
+def _hint_for(exc: Exception) -> str:
+    from pyVmomi import vim
+
+    if isinstance(exc, (NoVsphereRoleError, vim.fault.NotAuthenticated)):
+        return _ROLE_HINT
+    return _DOCTOR_HINT
+
+
 def _error_reply(exc: Exception, tool: str, decision: Optional[_gate.Decision] = None) -> dict:
     """The error envelope for a write tool, which vmware-policy audits as a failure.
 
@@ -148,7 +176,7 @@ def _error_reply(exc: Exception, tool: str, decision: Optional[_gate.Decision] =
     if isinstance(exc, _gate.GateRefusedError):
         hint = "Nothing was changed. Call the tool without confirm to see the blast radius."
     else:
-        hint = "Run 'vmware-storage doctor' to verify connectivity."
+        hint = _hint_for(exc)
     payload = {"error": msg, "hint": hint}
     if decision is not None and decision.deprecated:
         payload["deprecated"] = decision.deprecated
@@ -353,7 +381,7 @@ def list_all_datastores(
         return list_datastores(si, limit=limit)
     except Exception as e:
         logger.error("list_all_datastores failed: %s", e)
-        return {"error": _safe_error(e, "storage"), "hint": "Run 'vmware-storage doctor' to verify connectivity."}
+        return {"error": _safe_error(e, "storage"), "hint": _hint_for(e)}
 
 
 @mcp.tool(annotations={"readOnlyHint": True, "destructiveHint": False, "idempotentHint": True, "openWorldHint": True})
@@ -384,7 +412,7 @@ def browse_datastore(
         return datastore_browser.browse_datastore(si, datastore_name, path=path, pattern=pattern)
     except Exception as e:
         logger.error("browse_datastore failed: %s", e)
-        return {"error": _safe_error(e, "storage"), "hint": "Run 'vmware-storage doctor' to verify connectivity."}
+        return {"error": _safe_error(e, "storage"), "hint": _hint_for(e)}
 
 
 @mcp.tool(annotations={"readOnlyHint": True, "destructiveHint": False, "idempotentHint": True, "openWorldHint": True})
@@ -413,7 +441,7 @@ def scan_datastore_images(
         return datastore_browser.scan_images(si, datastore_name, path=path)
     except Exception as e:
         logger.error("scan_datastore_images failed: %s", e)
-        return {"error": _safe_error(e, "storage"), "hint": "Run 'vmware-storage doctor' to verify connectivity."}
+        return {"error": _safe_error(e, "storage"), "hint": _hint_for(e)}
 
 
 @mcp.tool(annotations={"readOnlyHint": True, "destructiveHint": False, "idempotentHint": True, "openWorldHint": True})
@@ -527,7 +555,7 @@ def get_iscsi_status(
         return _ops_get_iscsi_status(si, host_name)
     except Exception as e:
         logger.error("get_iscsi_status failed: %s", e)
-        return {"error": _safe_error(e, "storage"), "hint": "Run 'vmware-storage doctor' to verify connectivity."}
+        return {"error": _safe_error(e, "storage"), "hint": _hint_for(e)}
 
 
 @mcp.tool(annotations={"readOnlyHint": False, "destructiveHint": False, "idempotentHint": False, "openWorldHint": True})
@@ -748,7 +776,7 @@ def get_vsan_health(
         return _ops_get_vsan_health(si, cluster_name)
     except Exception as e:
         logger.error("get_vsan_health failed: %s", e)
-        return {"error": _safe_error(e, "storage"), "hint": "Run 'vmware-storage doctor' to verify connectivity."}
+        return {"error": _safe_error(e, "storage"), "hint": _hint_for(e)}
 
 
 @mcp.tool(annotations={"readOnlyHint": True, "destructiveHint": False, "idempotentHint": True, "openWorldHint": True})
@@ -779,7 +807,7 @@ def get_vsan_capacity(
         return _ops_get_vsan_capacity(si, cluster_name)
     except Exception as e:
         logger.error("get_vsan_capacity failed: %s", e)
-        return {"error": _safe_error(e, "storage"), "hint": "Run 'vmware-storage doctor' to verify connectivity."}
+        return {"error": _safe_error(e, "storage"), "hint": _hint_for(e)}
 
 
 @mcp.tool(annotations={"readOnlyHint": True, "destructiveHint": False, "idempotentHint": True, "openWorldHint": True})
@@ -814,7 +842,7 @@ def get_vsan_efficiency(
         return _ops_get_vsan_efficiency(si, cluster_name)
     except Exception as e:
         logger.error("get_vsan_efficiency failed: %s", e)
-        return {"error": _safe_error(e, "storage"), "hint": "Run 'vmware-storage doctor' to verify connectivity."}
+        return {"error": _safe_error(e, "storage"), "hint": _hint_for(e)}
 
 
 # ---------------------------------------------------------------------------
@@ -857,7 +885,7 @@ def list_fc_adapters(
         return _ops_list_fc_adapters(si, cluster=cluster, host=host, limit=limit, offset=offset)
     except Exception as e:
         logger.error("list_fc_adapters failed: %s", e)
-        return {"error": _safe_error(e, "storage"), "hint": "Run 'vmware-storage doctor' to verify connectivity."}
+        return {"error": _safe_error(e, "storage"), "hint": _hint_for(e)}
 
 
 @mcp.tool(annotations={"readOnlyHint": True, "destructiveHint": False, "idempotentHint": True, "openWorldHint": True})
@@ -922,7 +950,7 @@ def list_storage_device_paths(
         )
     except Exception as e:
         logger.error("list_storage_device_paths failed: %s", e)
-        return {"error": _safe_error(e, "storage"), "hint": "Run 'vmware-storage doctor' to verify connectivity."}
+        return {"error": _safe_error(e, "storage"), "hint": _hint_for(e)}
 
 
 # ---------------------------------------------------------------------------
@@ -964,7 +992,7 @@ def get_access_info(
         logger.error("get_access_info failed: %s", e)
         return {
             "error": _safe_error(e, "storage"),
-            "hint": "Run 'vmware-storage doctor' to verify connectivity.",
+            "hint": _hint_for(e),
         }