Add opt-in sanitizers and docstring warnings for user-controlled input

[andriytyurnikov]

Reworked per @JeremS's feedback. The original PR enforced newline/escape sanitization inside the hot path; this version is purely opt-in and changes no existing behavior.

Brotli charset has been split out to #35.

What this PR is now

Opt-in sanitizers (new public helpers in starfederation.datastar.clojure.api)

• assert-sse-line-safe! — throw if (str v) contains \n or \r. For [[id]], [[selector]], [[patch-mode]], [[element-ns]] when those values cross a trust boundary.
• assert-script-body-safe! — throw if script-text contains </script (any case). The HTML5 raw-text rule means escaping isn't safe; rejection is the only correct option.
• escape-script-attribute-value — return a string with & \" < > HTML-escaped, for [[attributes]] values that come from user input.
• assert-script-attribute-name-safe! — validate against [A-Za-z_][A-Za-z0-9_:.-]*, for attribute names you don't fully control.

All backed by a small utils/assert-no-newline! private helper.

Docstring warnings

> [!WARNING] blocks added to patch-elements!, patch-elements-seq!, remove-element!, patch-signals!, execute-script!, matching the style #31 introduced for console-log! / console-error! / redirect!. They call out which fields go raw onto the wire / into the script tag, and point at the helpers above.

What this PR is not

• No automatic validation in add-opt-line!, rework-options, or ->script-tag.
• No behavior change for existing callers.

Test plan

• bb test:bb — 62/62 pass (46 pre-existing + 16 new specs covering the 4 helpers).
• bb test:all — non-browser tests pass; the only failures are the pre-existing etaoin/geckodriver smoke tests.
• No diff vs main outside api.clj (warnings + helpers), utils.clj (helper impl), and api_test.clj (helper tests).

[JeremS]

Hi @andriytyurnikov, first of all, thanks for your interest in the SDK!

I already merged several of the small PRs you made. These have corrected quite a few mistakes, oversight and typos I made... That's is very helpful, thanks a lot.

This PR is quite a bit bigger than the others and it contains changes from the small PR you previously made. Here is what I'd like to do.

First I asked @Ramblurr to check out #30. I think the change should go through but since it's breaking, I'd like another set of eyes on this.

Second could you rebase if/when #30 is merged? It would shrink the size of the code to review.

Once that is done we can discuss the changes you propose here. Here is what I am thinking at the moment:

S1: I am not sure we need this, these are all value that should never be user generated.
S2: I am thinking along the same lines here

When In doubt, I always check the go and PHP SDKs. I may be wrong but i don't think they sanitize what is proposed in S1 and S2. We could propose sanitized version of the functions or provide sanitizing utilities though.

S3: I also check hyperlith when it comes to using brotli and the the charset is used there. I think this change should be merged.

Cheers,

[andriytyurnikov]

@JeremS truth to be told - I got real issues with Ruby SDK, and then I overreacted and started vibe-code infused bug bash rampage against clojure and ruby SDKs - I am not exposed to other platforms;

P.S. absence of 1.0.1 from npm is really frustrating, BTW

[JeremS]

@andriytyurnikov I don't mind someone using ai to try and find flaws in the SDK as long as it doesn't turn into a flood of PR I won't end up merging.

Now as I said the string sanitizing everywhere may not be a good idea since it meaning sanitizing strings that should only come from the developper, not users. As I said I could accept sanitizing tools and warning in docstrings.

I think the brotli charset config will go through in some form or another. I think it should be it's own PR though.

[andriy-swareco]

@JeremS I don't put much stock into PRs, feel welcome to discard them as you wish - it is your repo;
I understood that in the era of AI there will be much more forking activity, as coordination overhead piles up.

Game is changing, and ethical rules are fuzzy; just keep in mind - me here is as frustrated as you are.

[andriytyurnikov]

Closing in favor of two follow-ups, separating the parts you said you'd accept from the part where we disagree:

• Fix: use UTF-8 explicitly in brotli compress/decompress #35 — brotli UTF-8 charset, which you said should go through. Just that, on top of main.
• Proposal: safe-by-default patch/script API with unsafe-* escape hatches #36 — proposal for safe-by-default patch/script API with unsafe-* escape hatches. Filed as a separate alternative design rather than over-writing this PR; reasonable people can disagree on the right default here, and I'd rather lay out the rationale cleanly and let you decide than litigate it inline.

Thanks for the patient feedback on this — your call either way on #36.