chore: reject bare str at file-input sinks to prevent local-file read

[stuxf]

Type

🐛 Bug Fix
✅ Test

Changes

extract_file_data, audio_utils.process_audio_file (plus its tuple-content variant), audio_utils.calculate_request_duration, and the OCR _extract_file_metadata helpers accepted isinstance(x, (str, PathLike)) inputs and called open(x, "rb") on them. When these helpers run inside a proxy request handler the value comes from an attacker-controlled HTTP form field, so the open() is an arbitrary local file read on the proxy host — the file content is then forwarded to the upstream provider and base64-encoded into the response, giving the caller an exfiltration primitive (incl. /proc/self/environ for env-stored secrets).

Drop the str branch from the path-open union at every sink and raise ValueError with a clear migration message. pathlib.Path is preserved because it's a Python-level type HTTP form values can't fabricate. The same shape was already in place for the Black Forest Labs image-edit handler — this brings the rest of the file/audio/ocr pipeline in line.

Affected sinks (all in the litellm core, not provider-specific):

• litellm/litellm_core_utils/prompt_templates/common_utils.py:extract_file_data
• litellm/litellm_core_utils/audio_utils/utils.py:process_audio_file (and the tuple-content sub-branch)
• litellm/litellm_core_utils/audio_utils/utils.py:calculate_request_duration
• litellm/litellm_core_utils/audio_utils/utils.py:get_audio_file_content_hash (bare str now hashes the string itself rather than opening it — the hash function already had this fallback shape)
• litellm/ocr/main.py:_extract_file_metadata (also used by convert_file_document_to_url_document, the path the OCR proxy endpoint takes for {"type": "file", "file": ...} documents)

Variants checked and confirmed already safe in current code (no change needed):

• BFL image-edit handler — raises for non-URL strings, uses safe_get for URLs
• Bedrock Nova Canvas image-edit — str branch returns base64 as-is, only PathLike opens
• Bedrock and Vertex batch files transformations — str branch treats as JSONL content, only PathLike opens

Compatibility

• Operators: unaffected. The proxy form parser converts multipart UploadFile into the tuple shape these helpers accept; nothing in the proxy path supplied bare strings.
• SDK callers passing file=open("path", "rb") / file=("name", content) / file=Path("path") / file=b"...": unaffected. Every documented example in BerriAI/litellm-docs already uses one of these shapes.
• SDK callers passing file="literal/path.csv" as a bare string: minor breaking change. Get a ValueError pointing to the fix. Migrate to file=Path("literal/path.csv") (6 extra characters) or file=open("literal/path.csv", "rb") (the OpenAI SDK convention litellm mimics).

Test Plan

New / updated tests cover bare-str rejection at every patched sink plus the positive Path() path and existing tuple/bytes paths. Existing tests that passed bare-string paths to drive open() were updated to use Path().

Commits

• chore: reject bare str at file-input sinks to prevent local-file read

[codecov]

Codecov Report

❌ Patch coverage is 75.00000% with 5 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
litellm/ocr/main.py	0.00%	3 Missing ⚠️
litellm/litellm_core_utils/audio_utils/utils.py	84.61%	2 Missing ⚠️

📢 Thoughts on this report? Let us know!

[greptile-apps]

Greptile Summary

This PR closes an arbitrary local file read vulnerability in five file-input sinks (extract_file_data, process_audio_file, calculate_request_duration, the audio hash helper, and the OCR convert_file_document_to_url_document) by rejecting bare str inputs that could be attacker-controlled HTTP form values in proxy deployments. It also bundles a responses_api_bridge_check extension to route GPT-5 calls with AI-SDK-style reasoningSummary aliases through the Responses API and strip those aliases before non-bridged chat calls.

• LFI fix: str branches that called open(x, "rb") are replaced by ValueError; pathlib.Path (a Python-level type HTTP form values can't fabricate) remains accepted as an SDK convenience.
• Breaking change: SDK callers passing file="literal/path.csv" will now receive a ValueError with a migration hint; the error message directs them to Path(…) or open(…, "rb").
• reasoningSummary routing: New peek_reasoning_summary_aliases / strip_reasoning_summary_aliases_from_optional_params helpers in litellm/utils.py handle camelCase and snake_case aliases in top-level params and extra_body, merging them into reasoning_effort dict before the Responses bridge.

Confidence Score: 5/5

Safe to merge; the security fix is correctly applied at all five sinks and the reasoningSummary routing additions are well-tested.

The LFI patches are mechanical (split str/PathLike branches, raise on str) and the diff confirms no new open(str_input) call is introduced. The reasoningSummary bridge logic is covered by dedicated unit tests that exercise both the bridged and non-bridged paths. The only remaining gap — one stale docstring example — does not affect runtime behavior.

The aocr docstring in litellm/ocr/main.py still shows a bare-string file path that now raises at runtime; worth a quick update before the release notes go out.

Important Files Changed

Filename	Overview
litellm/litellm_core_utils/audio_utils/utils.py	Splits bare-str and PathLike branches in process_audio_file, calculate_request_duration, and get_audio_file_content_hash to close LFI; str raises ValueError except in hash helper which silently falls back
litellm/litellm_core_utils/prompt_templates/common_utils.py	extract_file_data now raises ValueError for bare str; PathLike branch is preserved; logic is correct
litellm/ocr/main.py	convert_file_document_to_url_document rejects bare str; aocr docstring still shows the now-broken bare-str example
litellm/main.py	responses_api_bridge_check extended to route on reasoning_summary alias; strip helpers strip aliases before non-bridged GPT-5 chat calls
litellm/utils.py	Adds peek_reasoning_summary_aliases and strip_reasoning_summary_aliases_from_optional_params; correctly uses membership tests to handle falsy values
litellm/llms/openai/chat/gpt_5_transformation.py	Import style reformatting only, no logic changes
tests/test_litellm/litellm_core_utils/test_audio_utils.py	Existing file-path tests updated to use pathlib.Path; new test_process_bare_str_path_rejected added
tests/test_litellm/ocr/test_ocr_file_input.py	Existing path tests migrated to pathlib.Path; test_should_reject_bare_str_path added; coverage is thorough
tests/test_litellm/test_main.py	New bridge-check tests for reasoning_summary routing and merging; reasoning_effort dict tests pass
tests/test_litellm/llms/openai/test_gpt5_transformation.py	New tests for peek/strip helpers and chat-path alias stripping; correctly verify alias removal
tests/test_litellm/llms/github_copilot/test_github_copilot_transformation.py	Mock patching hardened to handle both class-method and module-level instance paths; no regressions
tests/test_litellm/litellm_core_utils/prompt_templates/test_litellm_core_utils_prompt_templates_common_utils.py	New TestExtractFileDataBareStr suite covers rejection, Path acceptance, bytes, and tuple inputs
tests/test_litellm/llms/vertex_ai/gemini/test_vertex_ai_gemini_transformation.py	String-path tests migrated to pathlib.Path; assertions preserved; no regressions

_{Reviews (3): Last reviewed commit: "chore: reject bare str at file-input sin..." | Re-trigger Greptile}

[stuxf]

@greptileai

[oss-pr-review-agent-shin]

🤖 litellm-agent: Squash-merged into staging branch litellm_agent_oss_staging_05_11_2026. Staging PR: #27664

---

Triage Summary
Gathered PR data only — the triage LLM step did not produce a valid report, so failing-check classification and prior-signal reconciliation were skipped. 249 line(s) across 7 file(s) (+185/-64).

249 lines across 7 files (+185 / -64)

Merge Confidence: 5/5 ✅ READY
Ready to ship.

All checks green. Greptile 4/5, no blocking pattern findings, no CircleCI runs (OSS-typical).

[stuxf]

@greptileai