fix(realtime): reject unsupported image URL schemes; document fetch/file-read footguns

[AdirAmsalem]

Context

Follow-up to the JS SDK hardening. Same class of issue in the Python SDK's image/file input resolution — and the decision here was keep the conveniences, document them, and close the silent fall-through.

Changes

1. _image_to_base64 (decart/realtime/client.py) — reject unsupported URL schemes. A string that parsed as a URL but wasn't data:/http(s): (e.g. file://, ftp://, blob:) was returned verbatim as if it were raw base64, then failed opaquely at the API. It now raises InvalidInputError. Raw base64 and local file paths are unaffected (a single-char scheme like C:\ is treated as a Windows path, not a URL; raw base64 has no scheme).

2. Documented the footguns on both string sinks — _image_to_base64 and file_input_to_bytes (decart/process/request.py). Both, by design, fetch http(s) URLs and read local file paths. That's fine for trusted inputs (your own code, local files, a CLI/notebook), but a docstring security note now spells out that passing an untrusted/user-supplied string server-side is an SSRF risk (the fetch runs from your server) and a local-file-disclosure risk (the path is read from your server's disk). For untrusted input, resolve it yourself and pass bytes.

The http(s) fetch and local-file read behaviors are intentionally kept — only documented and made non-silent on bad schemes.

Test

New unit tests in tests/test_realtime_unit.py: raw-base64 passthrough, data: decode, and unsupported-scheme rejection. pytest tests/test_realtime_unit.py tests/test_process.py → 32 passed (pre-existing aiohttp deprecation warnings only).

---

Note

Medium Risk
Changes input validation and error behavior for realtime/process image paths; SSRF/file-read risks remain by design but are documented—misuse on servers is the main concern.

Overview
Hardens Python SDK image/file string resolution to match the JS SDK approach: keep http(s) fetch and local path reads for trusted use, but stop silently treating unknown URL schemes as raw base64.

In _image_to_base64, strings that parse as URLs with schemes other than data: / http / https (e.g. file://, ftp://, blob:) now raise InvalidInputError instead of being forwarded to the API as bogus base64. Raw base64 passthrough and Windows paths (C:\..., single-char scheme) stay unchanged.

Docstring security notes were added on file_input_to_bytes and _image_to_base64 warning that untrusted server-side strings can cause local file disclosure (path read) or SSRF (http(s) fetch); untrusted input should be resolved to bytes first.

Tests cover raw base64 passthrough, data: decoding, and rejection of unsupported schemes.

^{Reviewed by Cursor Bugbot for commit 7654d73. Bugbot is set up for automated code reviews on this repo. Configure here.}