feat(llc): Sanitize X-Stream-Client to prevent customers overriding internal values (v9)

[VelikovPetar]

Submit a pull request

Linear: FLU-565

Github Issue: #

Backport of: #2790

CLA

• I have signed the Stream CLA (required).
• The code changes follow best practices
• Code changes are tested (add some information if not applicable)

Description of the pull request

Hardens the X-Stream-Client header so SDK-identifying metadata can't be spoofed via StreamChatClient.updateSystemEnvironment or overridden through custom WebSocket query parameters.

SystemEnvironmentManager now sanitizes any SystemEnvironment it receives (both in the constructor and in updateEnvironment):

• Immutable fields — forced to internal defaults, custom values ignored:
  • sdkName (locked to stream-chat)
  • sdkVersion (locked to PACKAGE_VERSION)
  • osName (locked to CurrentPlatform.name)
• sdkIdentifier — only the one-way dart → flutter promotion is accepted. A flutter → dart demotion and any unknown identifier fall back to the current value. This lets the Flutter UI layer upgrade the identifier while preventing downgrades/spoofing.
• Overridable fields — continue to pass through as-is:
  • appName, appVersion, osVersion, deviceModel

WebSocket header ordering — the X-Stream-Client header is now applied after ...queryParameters in the connection params, so caller-supplied query parameters can no longer override it.

Doc comments on StreamChatClient.updateSystemEnvironment were updated to document the overridable vs. immutable fields.

Test instructions

Covered by unit tests in system_environment_manager_test.dart:

• sanitizes environment passed to the constructor
• sanitizes environment on update (immutable fields forced, unknown sdkIdentifier falls back)
• allows promoting sdkIdentifier dart → flutter
• ignores demotion flutter → dart

Run: melos run test --scope=stream_chat (or the single file above).

Screenshots / Videos

No UI changes.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 7b2a4abf-6017-42ff-9660-27415293b576

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feature/FLU-565_sanitize_x_stream_client

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[codecov]

Codecov Report

❌ Patch coverage is 95.00000% with 1 line in your changes missing coverage. Please review.
⚠️ Please upload report for BASE (v9@8158e27). Learn more about missing BASE report.

Files with missing lines	Patch %	Lines
packages/stream_chat/lib/src/ws/websocket.dart	0.00%	1 Missing ⚠️

Additional details and impacted files

@@          Coverage Diff          @@
##             v9    #2799   +/-   ##
=====================================
  Coverage      ?   66.32%           
=====================================
  Files         ?      429           
  Lines         ?    27114           
  Branches      ?        0           
=====================================
  Hits          ?    17983           
  Misses        ?     9131           
  Partials      ?        0           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.