fix: validate hex colours in hexColor() to prevent XML injection

hexColor() previously did no validation — just stripped '#' and
uppercased. If a non-hex string (like gradient XML) was passed, it
was silently embedded as an srgbClr val attribute, producing corrupt
OOXML that PowerPoint would repair by stripping entire slides.

Bug reproduction: LLM passes gradient XML or background XML as a
'color' parameter → hexColor uppercases it → solidFill embeds it as
<a:srgbClr val='<P:BG>...'/> → PowerPoint repair strips the slide.

Fix: hexColor() now validates input against /^#?[0-9A-Fa-f]{6}$/
and throws a descriptive error on invalid input, matching the same
regex used by requireHex(). Error message truncates long strings to
avoid dumping XML fragments into the console.

Signed-off-by: Simon Davies <simongdavies@users.noreply.github.com>

Author: simongdavies

builtin-modules/doc-core.json

@@ -3,8 +3,8 @@
   "description": "Format-agnostic document infrastructure — themes, colour validation, contrast utilities, input guards. Used by ha:pptx, ha:pdf, and other format modules.",
   "author": "system",
   "mutable": false,
-  "sourceHash": "sha256:b9119a600839812d",
-  "dtsHash": "sha256:1f311b99f56fdcbb",
+  "sourceHash": "sha256:f17eeec053c65a77",
+  "dtsHash": "sha256:4bbfced3ab780ce8",
   "importStyle": "named",
   "hints": {
     "overview": "Shared utilities for all document formats. Provides themes, colour validation (WCAG AA contrast), and input guards. You rarely import this directly — ha:pptx and ha:pdf re-use it internally.",

builtin-modules/src/doc-core.ts

@@ -15,13 +15,24 @@
 /**
  * Convert a hex colour string to normalised format (strip leading #, uppercase).
  * This is the **lenient** version — it does NOT throw on bad input.
- * Prefer `requireHex()` at public API boundaries; this is kept for
- * internal paths where the value has already been validated.
+ * Normalise and validate a hex colour string.
+ *
+ * Throws on invalid input (non-hex strings, XML fragments, named
+ * colours, rgb() notation, etc.) to prevent malformed OOXML output.
+ * Prefer `requireHex()` at public API boundaries for more descriptive
+ * error messages with parameter names.
  *
  * @param hex - Colour like "#2196F3" or "2196F3"
  * @returns Normalised colour like "2196F3"
+ * @throws {Error} If hex is not a valid 6-character hex colour
  */
 export function hexColor(hex: string): string {
+  if (typeof hex !== "string" || !/^#?[0-9A-Fa-f]{6}$/.test(hex)) {
+    throw new Error(
+      `Invalid hex colour: "${typeof hex === "string" && hex.length > 30 ? hex.slice(0, 30) + "..." : hex}". ` +
+        `Expected a 6-character hex string like "2196F3" or "#FF9800".`,
+    );
+  }
   return hex.replace(/^#/, "").toUpperCase();
 }
 

builtin-modules/src/types/ha-modules.d.ts

@@ -45,11 +45,16 @@ declare module "ha:doc-core" {
   /**
    * Convert a hex colour string to normalised format (strip leading #, uppercase).
    * This is the **lenient** version — it does NOT throw on bad input.
-   * Prefer `requireHex()` at public API boundaries; this is kept for
-   * internal paths where the value has already been validated.
+   * Normalise and validate a hex colour string.
+   *
+   * Throws on invalid input (non-hex strings, XML fragments, named
+   * colours, rgb() notation, etc.) to prevent malformed OOXML output.
+   * Prefer `requireHex()` at public API boundaries for more descriptive
+   * error messages with parameter names.
    *
    * @param hex - Colour like "#2196F3" or "2196F3"
    * @returns Normalised colour like "2196F3"
+   * @throws {Error} If hex is not a valid 6-character hex colour
    */
   export declare function hexColor(hex: string): string;
   /**