From ffcb20f7813084659ade185e64790f5a8d4e6be2 Mon Sep 17 00:00:00 2001
From: Simon McVittie <smcv@collabora.com>
Date: Fri, 21 Aug 2026 14:48:52 +0100
Subject: [PATCH] utils: Add a function to describe invalid characters in
 strings

Until now we have been using `%c` to show invalid characters, but in
general that will corrupt our output if the input is non-ASCII,
because the individual bytes of a UTF-8 string are not valid UTF-8 alone.

Signed-off-by: Simon McVittie <smcv@collabora.com>
---
 common/flatpak-utils-private.h |  2 ++
 common/flatpak-utils.c         | 31 +++++++++++++++++++++++++++++++
 tests/testcommon.c             | 33 +++++++++++++++++++++++++++++++++
 3 files changed, 66 insertions(+)

diff --git a/common/flatpak-utils-private.h b/common/flatpak-utils-private.h
index ab6efbbf0..67f3989ec 100644
--- a/common/flatpak-utils-private.h
+++ b/common/flatpak-utils-private.h
@@ -361,6 +361,8 @@ char * flatpak_escape_string (const char        *s,
 gboolean flatpak_validate_path_characters (const char *path,
                                            GError    **error);
 
+char *flatpak_describe_invalid_first_char (const char *s);
+
 gboolean running_under_sudo_root (void);
 
 void flatpak_set_debugging (gboolean debugging);
diff --git a/common/flatpak-utils.c b/common/flatpak-utils.c
index ae74dd152..4d55212e8 100644
--- a/common/flatpak-utils.c
+++ b/common/flatpak-utils.c
@@ -2533,6 +2533,37 @@ flatpak_validate_path_characters (const char *path,
   return TRUE;
 }
 
+/*
+ * Describe the first character of @s in a way that is useful for
+ * error messages about invalid strings.
+ */
+char *
+flatpak_describe_invalid_first_char (const char *s)
+{
+  gunichar c = g_utf8_get_char_validated (s, -1);
+
+  /* If s starts with valid UTF-8 and the character is printable,
+   * represent it as itself, for example:
+   * Branch can't contain "x" */
+  if (c > 0 && g_unichar_isprint (c) && !g_unichar_iszerowidth (c))
+    {
+      char buf[7] = { 0 };
+
+      g_unichar_to_utf8 (c, buf);
+      return g_strdup (buf);
+    }
+
+  /* If s starts with valid UTF-8 but the character is unprintable,
+   * represent it in Unicode codepoint notation, for example:
+   * Branch can't contain "U+000A" */
+  if (c != (gunichar) -1 && c != (gunichar) -2)
+    return g_strdup_printf ("U+%04X", c);
+
+  /* If it wasn't even valid UTF-8, resort to representing the byte:
+   * Branch can't contain "\xFF" */
+  return g_strdup_printf ("\\x%02X", (unsigned char) *s);
+}
+
 gboolean
 running_under_sudo_root (void)
 {
diff --git a/tests/testcommon.c b/tests/testcommon.c
index 4b23cd88d..89942525c 100644
--- a/tests/testcommon.c
+++ b/tests/testcommon.c
@@ -1,5 +1,6 @@
 #include "config.h"
 
+#include <locale.h>
 #include <string.h>
 #include <sys/types.h>
 #include <sys/wait.h>
@@ -998,6 +999,35 @@ test_dconf_paths (void)
     }
 }
 
+static void
+test_describe_invalid_char (void)
+{
+  static const char * const inputs[] =
+  {
+    ".",
+    "-",
+    "abc",
+    "\n",
+    "\xc3\xa6",           /* U+00E6 LATIN SMALL LETTER AE */
+    "\xcc\x88",           /* U+0308 COMBINING DIAERESIS */
+    "\xef\xbb\xbf",       /* U+FEFF ZERO WIDTH NO-BREAK SPACE */
+    "\xf0\x9f\x98\xb9",   /* U+1F639 CAT FACE WITH TEARS OF JOY */
+    "\xf0\x9f",           /* truncated valid UTF-8 */
+    "\xff",               /* not valid UTF-8 */
+  };
+
+  for (size_t i = 0; i < G_N_ELEMENTS (inputs); i++)
+    {
+      g_autofree char *escaped = flatpak_escape_string (inputs[i], FLATPAK_ESCAPE_DO_NOT_QUOTE);
+      g_autofree char *output = flatpak_describe_invalid_first_char (inputs[i]);
+
+      g_test_message ("First character of \"%s\": \"%s\"", escaped, output);
+      g_assert_nonnull (output);
+      g_assert_true (g_utf8_validate (escaped, -1, NULL));
+      g_assert_true (g_utf8_validate (output, -1, NULL));
+    }
+}
+
 static void
 test_envp_cmp (void)
 {
@@ -1353,6 +1383,8 @@ main (int argc, char *argv[])
 {
   int res;
 
+  setlocale (LC_ALL, "");
+
   g_test_init (&argc, &argv, NULL);
 
   g_test_add_func ("/common/has-path-prefix", test_has_path_prefix);
@@ -1370,6 +1402,7 @@ main (int argc, char *argv[])
   g_test_add_func ("/common/dconf-app-id", test_dconf_app_id);
   g_test_add_func ("/common/dconf-paths", test_dconf_paths);
   g_test_add_func ("/common/decompose-ref", test_decompose);
+  g_test_add_func ("/common/describe-invalid-char", test_describe_invalid_char);
   g_test_add_func ("/common/envp-cmp", test_envp_cmp);
   g_test_add_func ("/common/needs-quoting", test_needs_quoting);
   g_test_add_func ("/common/quote-argv", test_quote_argv);