Merge branch 'master' into prepare-10-1-1

Author: mykola-mokhnach

docs/The-starting-of-an-app-using-Appium-node-server-started-programmatically.md

@@ -1,7 +1,7 @@
 # Requirements
-- Installed Node.js 7 or greater. 
+- Installed Node.js 7 or greater.
 
-- At least an appium server instance installed via __npm__. 
+- At least an appium server instance installed via __npm__.
 
 # The basic principle.
 
@@ -10,7 +10,7 @@ It works the similar way as common [ChromeDriver](https://seleniumhq.github.io/s
 # How to prepare the local service before the starting
 
 
-## If there is no specific parameters then 
+## If there is no specific parameters then
 
 ```java
     import io.appium.java_client.service.local.AppiumDriverLocalService;
@@ -20,7 +20,7 @@ It works the similar way as common [ChromeDriver](https://seleniumhq.github.io/s
     service.start();
     ...
     service.stop();
-``` 
+```
 
 ### FYI
 
@@ -32,20 +32,23 @@ AppiumDriverLocalService service = AppiumDriverLocalService.buildDefaultService(
 
 It is more usual for UNIX/LINUX-like OS's. Also there are situations when should be used an another Node.JS instance, e.g. the instance which is installed in the directory that differs from one defined at the PATH environmental variable. The same may be true for Appium node server (it is related to _appium.js_ file (v <= 1.4.16) and _main.js_ (v >= 1.5.0)).
 
-At this case user is able to set up values of the **NODE_BINARY_PATH** (The environmental variable used to define the path to executable NodeJS file (node.exe for WIN and node for Linux/MacOS X)) and the **APPIUM_BINARY_PATH** (The environmental variable used to define the path to executable appium.js (1.4.x and lower) or main.js (1.5.x and higher)) environmental variables/system properties. Also it is possible to define these values programmatically: 
+At this case user is able to set up values of the **NODE_BINARY_PATH** (The environmental variable used to define the path to executable NodeJS file (node.exe for WIN and node for Linux/MacOS X)) and the **APPIUM_BINARY_PATH** (The environmental variable used to define the path to executable appium.js (1.4.x and lower) or main.js (1.5.x and higher)) environmental variables/system properties. Also it is possible to define these values programmatically:
 
 ```java
+import io.appium.java_client.service.local.AppiumDriverLocalService;
+import io.appium.java_client.service.local.AppiumServiceBuilder;
+
 //appium.node.js.exec.path
-System.setProperty(AppiumServiceBuilder.NODE_PATH , 
+System.setProperty(AppiumServiceBuilder.NODE_PATH,
 "the path to the desired node.js executable");
 
-System.setProperty(AppiumServiceBuilder.APPIUM_PATH , 
+System.setProperty(AppiumServiceBuilder.APPIUM_PATH,
 "the path to the desired appium.js or main.js");
 
 AppiumDriverLocalService service = AppiumDriverLocalService.buildDefaultService();
 ```
 
-## If there should be non default parameters specified then 
+## If there should be non default parameters specified then
 
 ```java
 import io.appium.java_client.service.local.AppiumDriverLocalService;
@@ -57,9 +60,9 @@ AppiumDriverLocalService service = AppiumDriverLocalService.
 buildService(new AppiumServiceBuilder().
 withArgument(GeneralServerFlag.TEMP_DIRECTORY,
                     "The_path_to_the_temporary_directory"));
-``` 
+```
 
-or 
+or
 
 ```java
 import io.appium.java_client.service.local.AppiumDriverLocalService;
@@ -70,64 +73,64 @@ import io.appium.java_client.service.local.flags.GeneralServerFlag;
 AppiumDriverLocalService service = new AppiumServiceBuilder().
 withArgument(GeneralServerFlag.TEMP_DIRECTORY,
                     "The_path_to_the_temporary_directory").build();
-``` 
+```
 
 Lists of available server side flags are here:
 
 - io.appium.java_client.service.local.flags.GeneralServerFlag;
 - io.appium.java_client.service.local.flags.AndroidServerFlag;
 - io.appium.java_client.service.local.flags.IOSServerFlag
 
- 
+
 ## Which parameters also can be defined
 
 - If it is necessary to define some specific port or any free port
 
 ```java
 new AppiumServiceBuilder().usingPort(4000);
-``` 
+```
 
-or 
+or
 
 ```java
 new AppiumServiceBuilder().usingAnyFreePort();
-``` 
+```
 
 - If it is necessary to use another IP address
 
 ```java
 new AppiumServiceBuilder().withIPAddress("127.0.0.1");
-``` 
+```
 
 - If it is necessary to define output log file
 
 ```java
-import java.io.File; 
+import java.io.File;
   ...
 
 new AppiumServiceBuilder().withLogFile(logFile);
-``` 
+```
 
 - If it is necessary to define another Node.js executable file
 
 ```java
 import java.io.File;
- 
+
 ...
 
 new AppiumServiceBuilder().usingDriverExecutable(nodeJSExecutable);
-``` 
+```
 
 - If it is necessary to define another appium.js/main.js file
 
 ```java
 import java.io.File;
- 
+
 ...
-//appiumJS is the full or relative path to 
+//appiumJS is the full or relative path to
 //the appium.js (v<=1.4.16) or main.js (v>=1.5.0)
 new AppiumServiceBuilder().withAppiumJS(new File(appiumJS));
-``` 
+```
 
 - It is possible to define server capabilities (node server v >= 1.5.0)
 
@@ -152,39 +155,39 @@ serverCapabilities.setCapability(MobileCapabilityType.DEVICE_NAME, "Android Emul
 serverCapabilities.setCapability(MobileCapabilityType.FULL_RESET, true);
 serverCapabilities.setCapability(MobileCapabilityType.NEW_COMMAND_TIMEOUT, 60);
 serverCapabilities.setCapability(MobileCapabilityType.APP, app.getAbsolutePath());
-serverCapabilities.setCapability(AndroidMobileCapabilityType.CHROMEDRIVER_EXECUTABLE, 
+serverCapabilities.setCapability(AndroidMobileCapabilityType.CHROMEDRIVER_EXECUTABLE,
 chrome.getAbsolutePath()); //this capability set can be used for all cases
 
 AppiumServiceBuilder builder = new AppiumServiceBuilder().
 withCapabilities(serverCapabilities);
 AppiumDriverLocalService service = builder.build();
 
 DesiredCapabilities clientCapabilities = new DesiredCapabilities();
-clientCapabilities.setCapability(AndroidMobileCapabilityType.APP_PACKAGE, 
+clientCapabilities.setCapability(AndroidMobileCapabilityType.APP_PACKAGE,
 "io.appium.android.apis");
-clientCapabilities.setCapability(AndroidMobileCapabilityType.APP_ACTIVITY, 
+clientCapabilities.setCapability(AndroidMobileCapabilityType.APP_ACTIVITY,
 ".view.WebView1");
 ```
 
 then
 
 ```java
-AndroidDriver<MobileElement> driver = 
+AndroidDriver<MobileElement> driver =
 new AndroidDriver<>(service, clientCapabilities);
 ```
 
-or 
+or
 
 ```java
-AndroidDriver<MobileElement> driver = 
+AndroidDriver<MobileElement> driver =
 new AndroidDriver<>(builder, clientCapabilities);
 ```
 
-or 
+or
 
 ```java
 service.start();
-AndroidDriver<MobileElement> driver = 
+AndroidDriver<MobileElement> driver =
 new AndroidDriver<>(service.getUrl(), clientCapabilities);
 ```
 
@@ -219,7 +222,7 @@ public AndroidDriver(org.openqa.selenium.remote.http.HttpClient.Factory httpClie
             org.openqa.selenium.Capabilities desiredCapabilities)
 
 public AndroidDriver(org.openqa.selenium.Capabilities desiredCapabilities)
-``` 
+```
 
 ```java
 public IOSDriver(URL remoteAddress,
@@ -247,20 +250,20 @@ public IOSDriver(org.openqa.selenium.remote.http.HttpClient.Factory httpClientFa
             org.openqa.selenium.Capabilities desiredCapabilities)
 
 public IOSDriver(org.openqa.selenium.Capabilities desiredCapabilities)
-``` 
+```
 
 An instance of __AppiumDriverLocalService__ which has passed through constructors will be stopped when
 
 ```java
   driver.quit();
-``` 
+```
 
 If it is necessary to keep the service alive during a long time then something like that is available
 
 ```java
   service.start();
-  
+
   ....
 
   new IOSDriver<MobileElement>(service.getUrl(), capabilities)
-``` 
+```

src/main/java/io/appium/java_client/internal/DirectConnectUrlSafety.java

@@ -0,0 +1,78 @@
+/*
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package io.appium.java_client.internal;
+
+import org.openqa.selenium.SessionNotCreatedException;
+
+import java.net.InetAddress;
+import java.net.URL;
+import java.net.UnknownHostException;
+
+/**
+ * Validates URLs used with {@code overrideServerUrl} (for example after a {@code directConnect}
+ * response). Refuses the override when any resolved address is loopback, link-local (including
+ * typical cloud metadata IPv4 link-local space), unspecified, or multicast.
+ *
+ * <p>This is not a full &quot;public internet only&quot; policy: RFC 1918 private space, shared
+ * address space ({@code 100.64.0.0/10}), IPv6 unique-local ({@code fc00::/7}), and other addresses
+ * outside the checks above are still accepted. Stricter control belongs at the application or
+ * network layer (allowlists, egress rules, etc.).
+ */
+public final class DirectConnectUrlSafety {
+
+    private DirectConnectUrlSafety() {
+    }
+
+    /**
+     * Ensures the given URL's host does not resolve to loopback, link-local, unspecified, or
+     * multicast addresses (see class documentation for what is still allowed).
+     *
+     * @param url candidate server URL
+     * @throws SessionNotCreatedException if the host is missing, cannot be resolved, or resolves
+     *         to any address in the disallowed categories
+     */
+    public static void requireSafeOverrideTarget(URL url) throws SessionNotCreatedException {
+        String host = url.getHost();
+        if (host == null || host.isEmpty()) {
+            throw new SessionNotCreatedException(
+                    "Refusing to override the server URL: the URL must include a non-empty host.");
+        }
+
+        final InetAddress[] addresses;
+        try {
+            addresses = InetAddress.getAllByName(host);
+        } catch (UnknownHostException e) {
+            throw new SessionNotCreatedException(
+                    "Refusing to override the server URL: cannot resolve host '" + host + "'.", e);
+        }
+
+        for (InetAddress address : addresses) {
+            if (isDisallowed(address)) {
+                throw new SessionNotCreatedException(String.format(
+                        "Refusing to override the server URL: host '%s' resolves to %s, which is not "
+                                + "allowed (loopback, link-local, unspecified, or multicast address).",
+                        host,
+                        address.getHostAddress()));
+            }
+        }
+    }
+
+    private static boolean isDisallowed(InetAddress address) {
+        return address.isLoopbackAddress()
+                || address.isLinkLocalAddress()
+                || address.isAnyLocalAddress()
+                || address.isMulticastAddress();
+    }
+}

src/main/java/io/appium/java_client/remote/AppiumCommandExecutor.java

@@ -18,6 +18,7 @@
 
 import com.google.common.base.Throwables;
 import io.appium.java_client.AppiumClientConfig;
+import io.appium.java_client.internal.DirectConnectUrlSafety;
 import io.appium.java_client.internal.ReflectionHelpers;
 import lombok.Getter;
 import org.jspecify.annotations.NullMarked;
@@ -155,9 +156,16 @@ protected HttpClient getClient() {
      * Override the http client in the HttpCommandExecutor class with a new http client instance with the given URL.
      * It uses the same http client factory and client config for the new http client instance
      * if the constructor got them.
-     * @param serverUrl A url to override.
+     *
+     * @param serverUrl URL to use for subsequent HTTP requests. Before switching clients, the host is
+     *                  resolved and the override is refused if any resolved address is loopback,
+     *                  link-local (including IPv4 link-local such as metadata-service ranges),
+     *                  unspecified ({@code 0.0.0.0} / {@code ::}), or multicast. Private (RFC 1918),
+     *                  carrier-grade NAT ({@code 100.64.0.0/10}), IPv6 unique-local ({@code fc00::/7}),
+     *                  and other non-special addresses are not rejected by this check.
      */
     protected void overrideServerUrl(URL serverUrl) {
+        DirectConnectUrlSafety.requireSafeOverrideTarget(serverUrl);
         HttpClient newClient = getHttpClientFactory().createClient(appiumClientConfig.baseUrl(serverUrl));
         setPrivateFieldValue(HttpCommandExecutor.class, "client", newClient);
     }

src/main/java/io/appium/java_client/service/local/AppiumDriverLocalService.java

@@ -118,6 +118,24 @@ public URL getUrl() {
         return basePath == null ? url : addSuffix(url, basePath);
     }
 
+    /**
+     * System property checked by Selenium {@code DriverFinder} when the executable path is not set
+     * explicitly. Matches {@link AppiumServiceBuilder#NODE_PATH}.
+     */
+    @Override
+    public String getDriverProperty() {
+        return AppiumServiceBuilder.NODE_PATH;
+    }
+
+    /**
+     * Environment variable checked by Selenium {@code DriverFinder} when the executable path is not
+     * set explicitly. Matches {@link AppiumServiceBuilder#NODE_PATH}.
+     */
+    @Override
+    public String getDriverEnvironmentVariable() {
+        return AppiumServiceBuilder.NODE_PATH;
+    }
+
     @Override
     public boolean isRunning() {
         lock.lock();

src/main/java/io/appium/java_client/service/local/AppiumServiceBuilder.java

@@ -64,11 +64,10 @@ public final class AppiumServiceBuilder
     public static final String APPIUM_PATH = "APPIUM_BINARY_PATH";
 
     /**
-     * The environmental variable used to define
-     * the path to executable NodeJS file (node.exe for WIN and
-     * node for Linux/MacOS X).
+     * System property and environment variable name for the Node.js executable path
+     * (node.exe on Windows, node on Linux/macOS).
      */
-    private static final String NODE_PATH = "NODE_BINARY_PATH";
+    public static final String NODE_PATH = "NODE_BINARY_PATH";
 
     public static final String BROADCAST_IP4_ADDRESS = "0.0.0.0";
     public static final String BROADCAST_IP6_ADDRESS = "::";