[heos] Fix login failure when password contains special characters

bundles/org.openhab.binding.heos/src/main/java/org/openhab/binding/heos/internal/resources/HeosCommands.java

@@ -12,9 +12,6 @@
  */
 package org.openhab.binding.heos.internal.resources;
 
-import java.net.URLEncoder;
-import java.nio.charset.StandardCharsets;
-
 import org.eclipse.jdt.annotation.NonNullByDefault;
 import org.eclipse.jdt.annotation.Nullable;
 
@@ -261,8 +258,8 @@ public static String playURL(String pid, String url) {
     }
 
     public static String signIn(String username, String password) {
-        String encodedUsername = urlEncode(username);
-        String encodedPassword = urlEncode(password);
+        String encodedUsername = encodeSpecialCharacters(username);
+        String encodedPassword = encodeSpecialCharacters(password);
         return "heos://system/sign_in?un=" + encodedUsername + "&pw=" + encodedPassword;
     }
 
@@ -320,9 +317,18 @@ public static String getToggleGroupMute(String gid) {
         return TOGGLE_GROUP_MUTE + gid;
     }
 
-    private static String urlEncode(String username) {
-        String encoded = URLEncoder.encode(username, StandardCharsets.UTF_8);
-        // however it cannot handle escaped @ signs
-        return encoded.replace("%40", "@");
+    /**
+     * Encode string according to HEOS CLI Protocol Specification version 1.17,
+     * chapter 3.1 Commands:
+     * <p>
+     * Note: Special characters, i.e <code>&</code>, <code>=</code>, and <code>%</code> in attribute/value needs
+     * to be encoded to '%26(&)', '%3D(=)', and '%25(%)'.
+     * </p>
+     *
+     * @param str String to encode
+     * @return Encoded string
+     */
+    private static String encodeSpecialCharacters(String str) {
+        return str.replace("%", "%25").replace("&", "%26").replace("=", "%3D");
     }
 }

bundles/org.openhab.binding.heos/src/main/java/org/openhab/binding/heos/internal/resources/Telnet.java

@@ -119,6 +119,7 @@ private void sendClear(String command) throws IOException {
             return;
         }
 
+        logger.trace("Sending command: {}", command);
         outStream.writeBytes(command);
         outStream.flush();
     }

bundles/org.openhab.binding.heos/src/test/java/org/openhab/binding/heos/internal/resources/HeosCommandsTest.java

@@ -0,0 +1,51 @@
+/*
+ * Copyright (c) 2010-2025 Contributors to the openHAB project
+ *
+ * See the NOTICE file(s) distributed with this work for additional
+ * information.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License 2.0 which is available at
+ * http://www.eclipse.org/legal/epl-2.0
+ *
+ * SPDX-License-Identifier: EPL-2.0
+ */
+package org.openhab.binding.heos.internal.resources;
+
+import static org.hamcrest.CoreMatchers.*;
+import static org.hamcrest.MatcherAssert.assertThat;
+
+import java.util.stream.Stream;
+
+import org.eclipse.jdt.annotation.NonNullByDefault;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.Arguments;
+import org.junit.jupiter.params.provider.MethodSource;
+
+/**
+ * Tests for {@link HeosCommands}.
+ *
+ * @author Jacob Laursen - Initial contribution
+ */
+@NonNullByDefault
+public class HeosCommandsTest {
+    /**
+     * Per HEOS CLI Protocol Specification, only '&', '=', and '%' must be URL-encoded in attribute values.
+     */
+    @ParameterizedTest
+    @MethodSource("provideTestCasesForSignInCommandShouldEncodePasswordCorrectly")
+    void signInCommandShouldEncodePasswordCorrectly(String username, String password, String expected) {
+        assertThat(HeosCommands.signIn(username, password), is(equalTo(expected)));
+    }
+
+    private static Stream<Arguments> provideTestCasesForSignInCommandShouldEncodePasswordCorrectly() {
+        return Stream.of( //
+                Arguments.of("user@gmail.com", "12345", "heos://system/sign_in?un=user@gmail.com&pw=12345"),
+                Arguments.of("user@foo.bar", "a&b", "heos://system/sign_in?un=user@foo.bar&pw=a%26b"),
+                Arguments.of("user@foo.bar", "1=1", "heos://system/sign_in?un=user@foo.bar&pw=1%3D1"),
+                Arguments.of("user@foo.bar", "%&%&", "heos://system/sign_in?un=user@foo.bar&pw=%25%26%25%26"),
+                Arguments.of("user@foo.bar", "!\"#$/`", "heos://system/sign_in?un=user@foo.bar&pw=!\"#$/`"),
+                Arguments.of("user@foo.bar", "føøbar", "heos://system/sign_in?un=user@foo.bar&pw=føøbar"),
+                Arguments.of("user@foo.bar", "%26%26", "heos://system/sign_in?un=user@foo.bar&pw=%2526%2526"));
+    }
+}