feat(auth): elicit Astrolabe URL on missing app password

When a tool requiring Nextcloud access is called without a stored app password (Login Flow v2 mode), the @require_scopes decorator now invokes MCP elicitation with a clickable Astrolabe settings URL — reconstructed from NEXTCLOUD_PUBLIC_ISSUER_URL / NEXTCLOUD_HOST — before raising ProvisioningRequiredError. Clients without elicitation support fall back to the existing text error. Surfaced by cbcoutinho/nextcloud-mcp-server#752, where users hit a 401 after OAuth and had no clickable URL to start Login Flow v2 from. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-02 12:02:18 +02:00
parent cb2b2e82d6
commit 2da8b38aeb
4 changed files with 352 additions and 2 deletions
@@ -0,0 +1,128 @@
+"""Unit tests for the MCP elicitation helpers."""
+
+from types import SimpleNamespace
+from unittest.mock import AsyncMock, MagicMock
+
+import pytest
+
+from nextcloud_mcp_server.auth.elicitation import (
+    ASTROLABE_SETTINGS_PATH,
+    _astrolabe_settings_url,
+    present_provisioning_required,
+)
+
+pytestmark = pytest.mark.unit
+
+
+@pytest.fixture(autouse=True)
+def clear_nc_env(monkeypatch):
+    """Strip the NC URL env vars by default; tests opt back in."""
+    monkeypatch.delenv("NEXTCLOUD_PUBLIC_ISSUER_URL", raising=False)
+    monkeypatch.delenv("NEXTCLOUD_HOST", raising=False)
+
+
+def test_astrolabe_settings_url_prefers_public_issuer(monkeypatch):
+    """Public issuer wins over host so the link is browser-reachable in Docker."""
+    monkeypatch.setenv("NEXTCLOUD_PUBLIC_ISSUER_URL", "https://nc.example.com")
+    monkeypatch.setenv("NEXTCLOUD_HOST", "http://internal:8080")
+
+    assert (
+        _astrolabe_settings_url() == f"https://nc.example.com{ASTROLABE_SETTINGS_PATH}"
+    )
+
+
+def test_astrolabe_settings_url_falls_back_to_host(monkeypatch):
+    """When only NEXTCLOUD_HOST is set, use it (and strip a trailing slash)."""
+    monkeypatch.setenv("NEXTCLOUD_HOST", "https://only-host.example.com/")
+
+    assert (
+        _astrolabe_settings_url()
+        == f"https://only-host.example.com{ASTROLABE_SETTINGS_PATH}"
+    )
+
+
+def test_astrolabe_settings_url_returns_none_when_unset():
+    """No NC URL configured → None (caller renders the tool-only message)."""
+    assert _astrolabe_settings_url() is None
+
+
+async def test_present_provisioning_required_elicits_with_url(monkeypatch):
+    """When NC URL is set and the client supports elicitation, send the URL."""
+    monkeypatch.setenv("NEXTCLOUD_PUBLIC_ISSUER_URL", "https://nc.example.com")
+
+    ctx = MagicMock()
+    ctx.elicit = AsyncMock(return_value=SimpleNamespace(action="accept", data=None))
+
+    result = await present_provisioning_required(ctx)
+
+    assert result == "accepted"
+    ctx.elicit.assert_awaited_once()
+    sent_message = ctx.elicit.await_args.kwargs["message"]
+    assert "https://nc.example.com/index.php/apps/astrolabe/settings" in sent_message
+    assert "nc_auth_provision_access" in sent_message
+
+
+async def test_present_provisioning_required_without_url(monkeypatch):
+    """When neither NC URL is set, fall back to the tool-only message."""
+    ctx = MagicMock()
+    ctx.elicit = AsyncMock(return_value=SimpleNamespace(action="accept", data=None))
+
+    result = await present_provisioning_required(ctx)
+
+    assert result == "accepted"
+    sent_message = ctx.elicit.await_args.kwargs["message"]
+    assert "astrolabe" not in sent_message.lower()
+    assert "nc_auth_provision_access" in sent_message
+
+
+async def test_present_provisioning_required_no_elicit_method():
+    """Contexts that don't expose ctx.elicit fall back to message_only."""
+
+    class _NoElicit:
+        pass
+
+    ctx = _NoElicit()
+
+    result = await present_provisioning_required(ctx)  # type: ignore[arg-type]
+
+    assert result == "message_only"
+
+
+async def test_present_provisioning_required_handles_not_implemented():
+    """SDK clients that don't support elicitation raise NotImplementedError."""
+    ctx = MagicMock()
+    ctx.elicit = AsyncMock(side_effect=NotImplementedError("client lacks elicit"))
+
+    result = await present_provisioning_required(ctx)
+
+    assert result == "message_only"
+
+
+async def test_present_provisioning_required_handles_unexpected_error():
+    """Any other elicit failure (e.g. transport) is fail-open to message_only."""
+    ctx = MagicMock()
+    ctx.elicit = AsyncMock(side_effect=RuntimeError("transport boom"))
+
+    result = await present_provisioning_required(ctx)
+
+    assert result == "message_only"
+
+
+async def test_present_provisioning_required_decline_returns_declined():
+    """User chose 'decline' on the prompt → propagate that to the caller."""
+    ctx = MagicMock()
+    ctx.elicit = AsyncMock(return_value=SimpleNamespace(action="decline", data=None))
+
+    result = await present_provisioning_required(ctx)
+
+    assert result == "declined"
+
+
+async def test_present_provisioning_required_cancel_returns_cancelled():
+    """User chose 'cancel' on the prompt → propagate that to the caller."""
+    ctx = MagicMock()
+    ctx.elicit = AsyncMock(return_value=SimpleNamespace(action="cancel", data=None))
+
+    result = await present_provisioning_required(ctx)
+
+    assert result == "cancelled"
@@ -4,13 +4,17 @@ Tests the third enforcement mode in scope_authorization.py that checks
 application-level scopes stored alongside app passwords.
 """

-from unittest.mock import AsyncMock, patch
+from types import SimpleNamespace
+from unittest.mock import AsyncMock, MagicMock, patch

 import pytest
+from mcp.server.fastmcp import Context

 from nextcloud_mcp_server.auth.scope_authorization import (
+    ProvisioningRequiredError,
    _get_stored_scopes,
    _scope_cache,
+    require_scopes,
 )

 pytestmark = pytest.mark.unit
@@ -91,3 +95,103 @@ async def test_get_stored_scopes_storage_error():
        pytest.raises(RuntimeError, match="DB error"),
    ):
        await _get_stored_scopes("alice")
+
+
+def _make_login_flow_ctx() -> MagicMock:
+    """Build a minimal Context shaped like the Login-Flow-v2 / OAuth case.
+
+    request_context.access_token must be non-None to pass the BasicAuth-mode
+    short-circuit in require_scopes; the token's actual scopes don't matter
+    because the Login-Flow-v2 branch checks stored scopes instead.
+    """
+    ctx = MagicMock()
+    ctx.request_context = SimpleNamespace(
+        access_token=SimpleNamespace(scopes=[], token="opaque")
+    )
+    ctx.elicit = AsyncMock(return_value=SimpleNamespace(action="accept", data=None))
+    return ctx
+
+
+async def test_decorator_elicits_before_raising_when_app_password_missing():
+    """When no app password is stored, the decorator must elicit a clickable
+    Astrolabe / Login-Flow-v2 prompt to the client *before* raising
+    ProvisioningRequiredError.
+
+    Why: an LLM-only error message ("call nc_auth_provision_access") is
+    unfriendly to humans whose MCP client supports elicitation. See
+    cbcoutinho/nextcloud-mcp-server#752.
+    """
+    ctx = _make_login_flow_ctx()
+
+    @require_scopes("notes.read")
+    async def fake_tool_missing_pwd(ctx: Context):  # noqa: ARG001
+        return "ok"
+
+    fake_settings = SimpleNamespace(enable_login_flow=True)
+    elicit_mock = AsyncMock(return_value="accepted")
+
+    with (
+        patch(
+            "nextcloud_mcp_server.auth.scope_authorization.get_settings",
+            return_value=fake_settings,
+        ),
+        patch(
+            "nextcloud_mcp_server.auth.scope_authorization._get_stored_scopes",
+            return_value=None,
+        ),
+        patch(
+            "nextcloud_mcp_server.auth.token_utils.extract_user_id_from_token",
+            return_value="alice",
+        ),
+        patch(
+            "nextcloud_mcp_server.auth.elicitation.present_provisioning_required",
+            elicit_mock,
+        ),
+        pytest.raises(ProvisioningRequiredError),
+    ):
+        await fake_tool_missing_pwd(ctx=ctx)
+
+    elicit_mock.assert_awaited_once_with(ctx)
+
+
+async def test_decorator_does_not_elicit_when_scopes_only_partially_missing():
+    """When the user *has* an app password but is missing some requested
+    scopes, the decorator raises InsufficientScopeError (step-up auth),
+    not ProvisioningRequiredError — and must not elicit the
+    provisioning-required prompt, because the user is already provisioned.
+    """
+    from nextcloud_mcp_server.auth.scope_authorization import (
+        InsufficientScopeError,
+    )
+
+    ctx = _make_login_flow_ctx()
+
+    @require_scopes("notes.write")
+    async def fake_tool_missing_scope(ctx: Context):  # noqa: ARG001
+        return "ok"
+
+    fake_settings = SimpleNamespace(enable_login_flow=True)
+    elicit_mock = AsyncMock()
+
+    with (
+        patch(
+            "nextcloud_mcp_server.auth.scope_authorization.get_settings",
+            return_value=fake_settings,
+        ),
+        patch(
+            "nextcloud_mcp_server.auth.scope_authorization._get_stored_scopes",
+            return_value=["notes.read"],  # has read, lacks write
+        ),
+        patch(
+            "nextcloud_mcp_server.auth.token_utils.extract_user_id_from_token",
+            return_value="alice",
+        ),
+        patch(
+            "nextcloud_mcp_server.auth.elicitation.present_provisioning_required",
+            elicit_mock,
+        ),
+        pytest.raises(InsufficientScopeError),
+    ):
+        await fake_tool_missing_scope(ctx=ctx)
+
+    elicit_mock.assert_not_awaited()