From 51c39fe8e87ae4cf507dda72a1eefb889a6cb33c Mon Sep 17 00:00:00 2001
From: Andriy Tyurnikov <Andriy.Tyurnikov@gmail.com>
Date: Wed, 29 Apr 2026 16:30:42 +0300
Subject: [PATCH] Make patch/script API safe by default with unsafe-* escape
 hatches

The five user-facing functions now validate / escape values that get
written raw onto the SSE wire or into a `<script>` tag, throwing on
inputs that would inject extra SSE lines or close the script tag.
Each has an `unsafe-*` twin that preserves the previous behavior for
callers who have already validated their input or know the value is
trusted.

Validations applied by the safe variants:

- `patch-elements!` / `patch-elements-seq!`: id, selector, patch-mode,
  element-ns must not contain CR/LF.
- `remove-element!`: same, plus the positional `selector`.
- `patch-signals!`: id must not contain CR/LF.
- `execute-script!`:
  - script body must not contain `</script` (any case);
  - id must not contain CR/LF;
  - attribute names validated against `[A-Za-z_][A-Za-z0-9_:.-]*`;
  - attribute values HTML-escaped (& " < >).

Atomic helpers backing the safe path are also public so callers can
validate at a different boundary or pre-validate before calling an
`unsafe-*` variant: `assert-sse-line-safe!`,
`assert-script-body-safe!`, `escape-script-attribute-value`,
`assert-script-attribute-name-safe!`.

The validations only reject inputs that are *already* spec violations
(SSE id/event lines are single-line; CSS selectors don't span lines;
HTML attribute names can't contain whitespace; `</script` always
closes a script tag regardless of escaping). No legitimate caller is
broken; the change tightens the contract from "trust developer input"
to "fail loudly on inputs that would silently inject events or HTML".

bb test:bb: 78/78.
---
 .../starfederation/datastar/clojure/api.clj   | 195 +++++++++++++++++-
 .../starfederation/datastar/clojure/utils.clj |  15 ++
 .../datastar/clojure/api_test.clj             | 144 +++++++++++++
 3 files changed, 347 insertions(+), 7 deletions(-)

diff --git a/libraries/sdk/src/main/starfederation/datastar/clojure/api.clj b/libraries/sdk/src/main/starfederation/datastar/clojure/api.clj
index 6d8fe4f..c0e3cde 100644
--- a/libraries/sdk/src/main/starfederation/datastar/clojure/api.clj
+++ b/libraries/sdk/src/main/starfederation/datastar/clojure/api.clj
@@ -265,6 +265,110 @@ Some scripts are provided:
   "element namespace: mathMl namespace"
   consts/element-namespace-mathml)
 
+;; -----------------------------------------------------------------------------
+;; Sanitizers
+;; -----------------------------------------------------------------------------
+;; The atomic helpers backing the safe-by-default validation. They are
+;; public so callers can also validate at a different boundary (e.g.
+;; before passing a value into one of the `unsafe-*` variants below).
+(defn assert-sse-line-safe!
+  "Throw an [[clojure.core/ex-info]] if `(str v)` contains `\\n` or `\\r`,
+  otherwise return `(str v)`.
+
+  Use this on values that will reach an SSE option line — [[id]],
+  [[selector]], [[patch-mode]], [[element-ns]] and friends — when those
+  values can come from user input. A newline in any of those would let
+  the caller append arbitrary SSE lines to the stream and forge events.
+
+  `name` is the field name and is included in the thrown error for
+  context (e.g. `\"selector\"`)."
+  [v name]
+  (u/assert-no-newline! v name))
+
+
+(defn assert-script-body-safe!
+  "Throw if `script-text` contains `</script` (case-insensitive); otherwise
+  return `script-text`.
+
+  HTML5 raw-text element parsing closes a `<script>` element as soon as
+  it sees `</script`, regardless of the trailing characters. Escaping
+  the occurrence would change the JS that runs, so the only safe option
+  is to reject it."
+  [script-text]
+  (when (and (string? script-text)
+             (re-find #"(?i)</script" script-text))
+    (throw (ex-info "Script content must not contain '</script' (would close the tag)."
+                    {:script script-text})))
+  script-text)
+
+
+(defn escape-script-attribute-value
+  "Return `v` (coerced to a string) with the four HTML attribute-context
+  characters escaped: `&`, `\"`, `<`, `>`. Use it on values you put into
+  the [[attributes]] map of [[execute-script!]] when those values come
+  from untrusted input — without escaping, a value containing `\"` can
+  break out of the attribute and inject extra attributes."
+  [v]
+  (-> (str v)
+      (.replace "&" "&amp;")
+      (.replace "\"" "&quot;")
+      (.replace "<" "&lt;")
+      (.replace ">" "&gt;")))
+
+
+(def ^:private valid-attr-name-re #"[A-Za-z_][A-Za-z0-9_:.-]*")
+
+(defn assert-script-attribute-name-safe!
+  "Throw if `(name k)` doesn't match `[A-Za-z_][A-Za-z0-9_:.-]*`; otherwise
+  return `(name k)`."
+  [k]
+  (let [n (name k)]
+    (when-not (re-matches valid-attr-name-re n)
+      (throw (ex-info (str "Invalid script attribute name: " (pr-str n))
+                      {:attribute n})))
+    n))
+
+
+;; -----------------------------------------------------------------------------
+;; Patch elements / signals / scripts
+;; -----------------------------------------------------------------------------
+;; Each user-facing function comes in two flavors:
+;; - the canonical name (e.g. `patch-elements!`) is **safe by default** —
+;;   values that get written raw onto the SSE wire or into a `<script>`
+;;   tag are validated/escaped before being sent, throwing on injection.
+;; - an `unsafe-*` twin skips that validation, for the case where the
+;;   developer has already validated the input or knows the value is
+;;   trusted.
+;; The atomic helpers backing the safe path ([[assert-sse-line-safe!]],
+;; [[assert-script-body-safe!]], [[escape-script-attribute-value]],
+;; [[assert-script-attribute-name-safe!]]) are public above so that
+;; callers can also validate at a different boundary.
+
+(defn- validate-element-line-opts! [opts]
+  (when-let [v (common/id opts)]                 (assert-sse-line-safe! v "id"))
+  (when-let [v (common/selector opts)]           (assert-sse-line-safe! v "selector"))
+  (when-let [v (common/patch-mode opts)]         (assert-sse-line-safe! v "patch-mode"))
+  (when-let [v (common/element-namespace opts)]  (assert-sse-line-safe! v "element-ns"))
+  opts)
+
+
+(defn unsafe-patch-elements!
+  "Like [[patch-elements!]] but skips the safe-by-default validation of
+  option-line values. Use only when you've already validated [[id]],
+  [[selector]], [[patch-mode]] and [[element-ns]] yourself, or know they
+  are trusted.
+
+  > [!WARNING]
+  > [[id]], [[selector]], [[patch-mode]] and [[element-ns]] are written
+  > verbatim onto a single line of the SSE wire format. A `\\n` or `\\r`
+  > in any of these lets the caller inject arbitrary SSE lines (and
+  > forge whole events) into the stream."
+  ([sse-gen elements]
+   (unsafe-patch-elements! sse-gen elements {}))
+  ([sse-gen elements opts]
+   (elements/patch-elements! sse-gen elements opts)))
+
+
 (defn patch-elements!
   "Send HTML elements to the browser to be patched into the DOM.
 
@@ -284,21 +388,45 @@ Some scripts are provided:
   Return value:
   - `false` if the connection is closed
   - `true` otherwise
-  "
+
+  Safe by default: throws if [[id]], [[selector]], [[patch-mode]] or
+  [[element-ns]] contains a `\\n` or `\\r`. Use
+  [[unsafe-patch-elements!]] to skip the check."
   ([sse-gen elements]
    (patch-elements! sse-gen elements {}))
   ([sse-gen elements opts]
+   (validate-element-line-opts! opts)
    (elements/patch-elements! sse-gen elements opts)))
 
 
+(defn unsafe-patch-elements-seq!
+  "Like [[patch-elements-seq!]] but skips the safe-by-default validation.
+  See [[unsafe-patch-elements!]]'s warning."
+  ([sse-gen elements]
+   (unsafe-patch-elements-seq! sse-gen elements {}))
+  ([sse-gen elements opts]
+   (elements/patch-elements-seq! sse-gen elements opts)))
+
+
 (defn patch-elements-seq!
-  "Same as [[patch-elements!]] except that it takes a seq of elements."
+  "Same as [[patch-elements!]] except that it takes a seq of elements.
+
+  Safe by default; see [[unsafe-patch-elements-seq!]] to skip validation."
   ([sse-gen elements]
    (patch-elements-seq! sse-gen elements {}))
   ([sse-gen elements opts]
+   (validate-element-line-opts! opts)
    (elements/patch-elements-seq! sse-gen elements opts)))
 
 
+(defn unsafe-remove-element!
+  "Like [[remove-element!]] but skips the safe-by-default validation.
+  See [[unsafe-patch-elements!]]'s warning."
+  ([sse-gen selector]
+   (unsafe-remove-element! sse-gen selector {}))
+  ([sse-gen selector opts]
+   (elements/remove-element! sse-gen selector opts)))
+
 
 (defn remove-element!
   "Remove element(s) from the dom. It is a convenience function using
@@ -319,13 +447,26 @@ Some scripts are provided:
   Return value:
   - `false` if the connection is closed
   - `true` otherwise
-  "
+
+  Safe by default: throws if `selector` or [[id]] contains a `\\n` or
+  `\\r`. Use [[unsafe-remove-element!]] to skip the check."
   ([sse-gen selector]
    (remove-element! sse-gen selector {}))
   ([sse-gen selector opts]
+   (assert-sse-line-safe! selector "selector")
+   (when-let [v (common/id opts)] (assert-sse-line-safe! v "id"))
    (elements/remove-element! sse-gen selector opts)))
 
 
+(defn unsafe-patch-signals!
+  "Like [[patch-signals!]] but skips the safe-by-default validation of
+  [[id]]. See [[unsafe-patch-elements!]]'s warning."
+  ([sse-gen signals-content]
+   (unsafe-patch-signals! sse-gen signals-content {}))
+  ([sse-gen signals-content opts]
+   (signals/patch-signals! sse-gen signals-content opts)))
+
+
 (defn patch-signals!
   "
   Send signals to the browser using
@@ -348,10 +489,13 @@ Some scripts are provided:
   Return value:
   - `false` if the connection is closed
   - `true` otherwise
-  "
+
+  Safe by default: throws if [[id]] contains a `\\n` or `\\r`. Use
+  [[unsafe-patch-signals!]] to skip the check."
   ([sse-gen signals-content]
    (patch-signals! sse-gen signals-content {}))
   ([sse-gen signals-content opts]
+   (when-let [v (common/id opts)] (assert-sse-line-safe! v "id"))
    (signals/patch-signals! sse-gen signals-content opts)))
 
 
@@ -373,6 +517,34 @@ Some scripts are provided:
   (signals/get-signals ring-request))
 
 
+(defn unsafe-execute-script!
+  "Like [[execute-script!]] but skips the safe-by-default validation /
+  escaping of `script-text` and [[attributes]].
+
+  > [!WARNING]
+  > `script-text` is interpolated as raw HTML inside the `<script>` tag,
+  > and each value in [[attributes]] is interpolated raw inside a
+  > double-quoted attribute. A `</script` substring in the body or a
+  > `\\\"` in an attribute value lets the caller close the tag and
+  > inject HTML/JS."
+  ([sse-gen script-text]
+   (unsafe-execute-script! sse-gen script-text {}))
+  ([sse-gen script-text opts]
+   (scripts/execute-script! sse-gen script-text opts)))
+
+
+(defn- sanitize-script-attributes [opts]
+  (if-let [attrs (common/attributes opts)]
+    (assoc opts common/attributes
+           (reduce-kv (fn [m k v]
+                        (assoc m
+                               (assert-script-attribute-name-safe! k)
+                               (escape-script-attribute-value v)))
+                      {}
+                      attrs))
+    opts))
+
+
 (defn execute-script!
   "
   Construct a HTML script tag using `script-text` as its content. Then sends it
@@ -396,11 +568,20 @@ Some scripts are provided:
   Return value:
   - `false` if the connection is closed
   - `true` otherwise
-  "
+
+  Safe by default:
+  - throws if `script-text` contains `</script` (any case);
+  - throws if [[id]] contains `\\n`/`\\r`;
+  - validates each attribute name in [[attributes]] and HTML-escapes
+    each value (`& \" < >`) before they reach the script tag.
+
+  Use [[unsafe-execute-script!]] if you need to skip the validation."
   ([sse-gen script-text]
-   (scripts/execute-script! sse-gen script-text {}))
+   (execute-script! sse-gen script-text {}))
   ([sse-gen script-text opts]
-   (scripts/execute-script! sse-gen script-text opts)))
+   (assert-script-body-safe! script-text)
+   (when-let [v (common/id opts)] (assert-sse-line-safe! v "id"))
+   (scripts/execute-script! sse-gen script-text (sanitize-script-attributes opts))))
 
 
 
diff --git a/libraries/sdk/src/main/starfederation/datastar/clojure/utils.clj b/libraries/sdk/src/main/starfederation/datastar/clojure/utils.clj
index d466b93..5147ad2 100644
--- a/libraries/sdk/src/main/starfederation/datastar/clojure/utils.clj
+++ b/libraries/sdk/src/main/starfederation/datastar/clojure/utils.clj
@@ -57,6 +57,21 @@
   (not (string/blank? s)))
 
 
+(defn assert-no-newline!
+  "Throw an [[ex-info]] if `(str v)` contains `\\n` or `\\r`.
+
+  Used to defend against SSE event injection: option/id values are written
+  to a single line of the SSE wire format, so a newline in user-controlled
+  input would let an attacker append arbitrary lines (and forge whole
+  events). `name` is included in the error for context. Returns `(str v)`."
+  [v ^String name]
+  (let [s (str v)]
+    (when (or (.contains s "\n") (.contains s "\r"))
+      (throw (ex-info (str name " must not contain newlines or carriage returns.")
+                      {:value v :name name})))
+    s))
+
+
 (defn merge-transient!
   "Merge a map `m` into a transient map `tm`.
   Returns the transient map without calling [[persistent!]] on it."
diff --git a/src/test/core-sdk/starfederation/datastar/clojure/api_test.clj b/src/test/core-sdk/starfederation/datastar/clojure/api_test.clj
index 9308a62..aef46ba 100644
--- a/src/test/core-sdk/starfederation/datastar/clojure/api_test.clj
+++ b/src/test/core-sdk/starfederation/datastar/clojure/api_test.clj
@@ -354,3 +354,147 @@
 
 (comment
   (ltr/run-test-var #'test-execute-script!))
+
+
+;; -----------------------------------------------------------------------------
+;; Sanitizer helpers
+;; -----------------------------------------------------------------------------
+;; The atomic helpers backing the safe-by-default validation, exposed so
+;; callers can also validate at a different boundary.
+(defn- threw? [thunk]
+  (try (thunk) false (catch Exception _ true)))
+
+(defdescribe test-assert-sse-line-safe!
+  (describe d*/assert-sse-line-safe!
+    (specify "passes through clean values"
+      (expect (= "1" (d*/assert-sse-line-safe! "1" "id")))
+      (expect (= "#main" (d*/assert-sse-line-safe! "#main" "selector")))
+      (expect (= "" (d*/assert-sse-line-safe! "" "id"))))
+    (specify "coerces to string"
+      (expect (= "42" (d*/assert-sse-line-safe! 42 "id"))))
+    (specify "throws on \\n"
+      (expect (threw? #(d*/assert-sse-line-safe! "1\nevent: bad" "id"))))
+    (specify "throws on \\r"
+      (expect (threw? #(d*/assert-sse-line-safe! "1\rmalicious" "id"))))
+    (specify "throws on \\r\\n"
+      (expect (threw? #(d*/assert-sse-line-safe! "x\r\ny" "selector"))))))
+
+
+(defdescribe test-assert-script-body-safe!
+  (describe d*/assert-script-body-safe!
+    (specify "passes through clean script bodies"
+      (expect (= "alert(1)" (d*/assert-script-body-safe! "alert(1)")))
+      (expect (= "" (d*/assert-script-body-safe! ""))))
+    (specify "lenient on non-string (consistent with execute-script! type expectations)"
+      (expect (= :test (d*/assert-script-body-safe! :test))))
+    (specify "throws on </script (lowercase)"
+      (expect (threw? #(d*/assert-script-body-safe! "</script>"))))
+    (specify "throws on </SCRIPT (any case)"
+      (expect (threw? #(d*/assert-script-body-safe! "x; </ScRiPt foo"))))))
+
+
+(defdescribe test-escape-script-attribute-value
+  (describe d*/escape-script-attribute-value
+    (specify "passes through clean values"
+      (expect (= "module" (d*/escape-script-attribute-value "module")))
+      (expect (= "" (d*/escape-script-attribute-value ""))))
+    (specify "coerces to string"
+      (expect (= "1" (d*/escape-script-attribute-value 1))))
+    (specify "escapes the four HTML attribute-context characters"
+      (expect (= "a&quot;b" (d*/escape-script-attribute-value "a\"b")))
+      (expect (= "&amp;" (d*/escape-script-attribute-value "&")))
+      (expect (= "&lt;a&gt;" (d*/escape-script-attribute-value "<a>"))))
+    (specify "escapes & before quotes (no double-escape)"
+      (expect (= "&amp;quot;" (d*/escape-script-attribute-value "&quot;"))))))
+
+
+(defdescribe test-assert-script-attribute-name-safe!
+  (describe d*/assert-script-attribute-name-safe!
+    (specify "accepts valid names"
+      (expect (= "type" (d*/assert-script-attribute-name-safe! "type")))
+      (expect (= "data-x" (d*/assert-script-attribute-name-safe! :data-x)))
+      (expect (= "x:y" (d*/assert-script-attribute-name-safe! "x:y"))))
+    (specify "throws on names with whitespace or =\""
+      (expect (threw? #(d*/assert-script-attribute-name-safe! "x onclick=foo")))
+      (expect (threw? #(d*/assert-script-attribute-name-safe! "x\"y"))))
+    (specify "throws on empty"
+      (expect (threw? #(d*/assert-script-attribute-name-safe! ""))))))
+
+
+(comment
+  (ltr/run-test-var #'test-assert-sse-line-safe!)
+  (ltr/run-test-var #'test-assert-script-body-safe!)
+  (ltr/run-test-var #'test-escape-script-attribute-value)
+  (ltr/run-test-var #'test-assert-script-attribute-name-safe!))
+
+
+;; -----------------------------------------------------------------------------
+;; Safe-by-default behavior
+;; -----------------------------------------------------------------------------
+;; The five public patch/script functions validate their option-line and
+;; script inputs by default. The `unsafe-*` twins skip the validation.
+(defdescribe test-safe-by-default-rejects-injection
+  (describe "patch-elements! rejects newlines in option lines"
+    (specify "id"
+      (expect (threw? #(d*/patch-elements! (at/->sse-gen) "x" {d*/id "1\nevent: bad"}))))
+    (specify "selector"
+      (expect (threw? #(d*/patch-elements! (at/->sse-gen) "x" {d*/selector "x\nevent: bad"}))))
+    (specify "patch-mode"
+      (expect (threw? #(d*/patch-elements! (at/->sse-gen) "x" {d*/patch-mode "after\nevent: bad"}))))
+    (specify "element-ns"
+      (expect (threw? #(d*/patch-elements! (at/->sse-gen) "x" {d*/element-ns "svg\nevent: bad"})))))
+
+  (describe "patch-elements-seq! rejects newlines"
+    (specify "selector"
+      (expect (threw? #(d*/patch-elements-seq! (at/->sse-gen) ["x"] {d*/selector "x\ny"})))))
+
+  (describe "remove-element! rejects newlines"
+    (specify "selector positional arg"
+      (expect (threw? #(d*/remove-element! (at/->sse-gen) "#x\nevent: bad"))))
+    (specify "id"
+      (expect (threw? #(d*/remove-element! (at/->sse-gen) "#x" {d*/id "1\nbad"})))))
+
+  (describe "patch-signals! rejects newlines"
+    (specify "id"
+      (expect (threw? #(d*/patch-signals! (at/->sse-gen) "{}" {d*/id "1\nbad"})))))
+
+  (describe "execute-script! defends the script tag"
+    (specify "rejects </script in body (lowercase)"
+      (expect (threw? #(d*/execute-script! (at/->sse-gen) "</script>"))))
+    (specify "rejects </SCRIPT in body (any case)"
+      (expect (threw? #(d*/execute-script! (at/->sse-gen) "x; </ScRiPt foo"))))
+    (specify "escapes attribute values"
+      (expect (= (d*/execute-script! (at/->sse-gen) "x"
+                                     {d*/auto-remove false
+                                      d*/attributes {"data-x" "a\" data-evil=\"x"}})
+                 (script-event
+                   "<script data-x=\"a&quot; data-evil=&quot;x\">x</script>"))))
+    (specify "rejects malformed attribute names"
+      (expect (threw? #(d*/execute-script! (at/->sse-gen) "x"
+                                           {d*/attributes {"x onclick=foo" "1"}}))))))
+
+
+(defdescribe test-unsafe-variants-skip-validation
+  (describe "unsafe-* twins do not validate"
+    (specify "unsafe-patch-elements! lets the injected line through"
+      (let [out (d*/unsafe-patch-elements! (at/->sse-gen) "x" {d*/id "1\nevent: bad"})]
+        (expect (.contains ^String out "id: 1\nevent: bad"))))
+
+    (specify "unsafe-patch-signals! lets the injected line through"
+      (let [out (d*/unsafe-patch-signals! (at/->sse-gen) "{}" {d*/id "1\nbad"})]
+        (expect (.contains ^String out "id: 1\nbad"))))
+
+    (specify "unsafe-remove-element! lets the injected selector through"
+      (let [out (d*/unsafe-remove-element! (at/->sse-gen) "#x\nevent: bad")]
+        (expect (.contains ^String out "selector #x\nevent: bad"))))
+
+    (specify "unsafe-execute-script! does not escape attribute values"
+      (let [out (d*/unsafe-execute-script! (at/->sse-gen) "alert(1)"
+                                           {d*/auto-remove false
+                                            d*/attributes {"data-x" "a\" b"}})]
+        (expect (.contains ^String out "data-x=\"a\" b\""))))))
+
+
+(comment
+  (ltr/run-test-var #'test-safe-by-default-rejects-injection)
+  (ltr/run-test-var #'test-unsafe-variants-skip-validation))