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>

tests/unit/test_scope_authorization_stored.py

@@ -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()