Summary

• Problem: Telegram media downloads still force local target DNS resolution even when the channel is configured with an explicit HTTP proxy.
• Why it matters: proxy-backed installs regress with could not download media on Bot API file downloads because the proxy is supposed to resolve Telegram CDN hostnames, not the local sandbox.
• What changed: added a trusted explicit-proxy guarded-fetch mode that keeps hostname-policy checks but skips local target DNS pinning, then wired Telegram media downloads to opt into that path.
• What did NOT change (scope boundary): env-proxy behavior, generic direct-fetch SSRF policy, and Telegram text/API request routing outside the media download path.

Change Type (select all)

• Bug fix
• Feature
• Refactor required for the fix
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Closes Telegram media download fails through proxy since v2026.4.8 (regression from DNS pinning change) #66245
• Related [Bug]: memory_search remote embeddings fail with ENOTFOUND when env proxy is configured — withRemoteHttpResponse skips TRUSTED_ENV_PROXY mode #52162
• This PR fixes a bug or regression

Root Cause (if applicable)

• Root cause: src/media/fetch.ts always wrapped media downloads in strict guarded-fetch mode, so explicit Telegram proxy dispatcher policies still ran resolvePinnedHostnameWithPolicy() on the target hostname before dialing the proxy.
• Missing detection / guardrail: there was no regression coverage for explicit-proxy media downloads that must preserve hostname allowlists while skipping local target DNS resolution.
• Contributing context (if known): #52162 fixed the env-proxy variant for provider HTTP helpers, but Telegram media downloads use explicit proxy dispatchers on a different path.

Regression Test Plan (if applicable)

• Coverage level that should have caught this:
  • Unit test
  • Seam / integration test
  • End-to-end test
  • Existing coverage already sufficient
• Target test or file: src/infra/net/fetch-guard.ssrf.test.ts, src/media/fetch.test.ts, extensions/telegram/src/bot/delivery.resolve-media-retry.test.ts
• Scenario the test should lock in: explicit Telegram proxy downloads skip target DNS pinning, still enforce hostname allowlists, and propagate the trusted explicit-proxy intent through the media fetch seam.
• Why this is the smallest reliable guardrail: the bug lives in the shared guarded-fetch/media seam; these tests hit the actual policy handoff without needing a live proxy fixture.
• Existing test that already covers this (if any): N/A
• If no new test is added, why not: N/A

User-visible / Behavior Changes

• Telegram media downloads work again behind operator-configured explicit HTTP proxies after v2026.4.8.

Diagram (if applicable)

Before:
[Telegram media download] -> [strict guarded fetch] -> [local DNS pin target host] -> [proxy-backed install fails]

After:
[Telegram media download] -> [trusted explicit-proxy guarded fetch] -> [hostname policy check] -> [proxy resolves target DNS] -> [download succeeds]

Security Impact (required)

• New permissions/capabilities? (No)
• Secrets/tokens handling changed? (No)
• New/changed network calls? (No)
• Command/tool execution surface changed? (No)
• Data access scope changed? (No)
• If any Yes, explain risk + mitigation: N/A

Repro + Verification

Environment

• OS: macOS
• Runtime/container: local Node 22 dev checkout
• Model/provider: N/A
• Integration/channel (if any): Telegram
• Relevant config (redacted): channels.telegram.proxy=http://<proxy-host>:8888

Steps

1. Configure Telegram with an explicit HTTP proxy.
2. Trigger a Bot API media download (getFile + file fetch).
3. Observe the guarded-fetch path used for the download.

Expected

• The explicit proxy resolves the target hostname after hostname-policy checks, and the download completes.

Actual

• The old path resolved the target locally before dialing the proxy, which broke proxy-backed installs and surfaced as could not download media.

Evidence

• Failing test/log before + passing after
• Trace/log snippets
• Screenshot/recording
• Perf numbers (if relevant)

Human Verification (required)

• Verified scenarios: targeted serial tests for fetch-guard, media fetch, and Telegram media resolution; full pnpm build.
• Edge cases checked: explicit proxy on localhost with allowPrivateProxy, off-allowlist target still blocked in trusted explicit-proxy mode.
• What you did not verify: live Telegram media download against a real proxy endpoint.

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

Compatibility / Migration

• Backward compatible? (Yes)
• Config/env changes? (No)
• Migration needed? (No)
• If yes, exact upgrade steps: N/A

Risks and Mitigations

• Risk: trusted explicit-proxy mode could look like an SSRF widening if it skipped hostname policy too.
  • Mitigation: the new path still enforces hostname allowlists and literal-host blocking before the proxy request, and tests lock that behavior in.