feat(aicore): transparent proxy routing and BTP Destination Service mode (Option 3)

[tiagoek]

Summary

Implements Option 3 from the AFSDK-4306 security alignment meeting (2026-08-14): "Hide the ugliness in the SDK" — agent code is identical in all environments; the deployer controls routing by choosing which env vars to inject.

Tracking: AFSDK-4414 / HASI2026203 (CVE 9.9)
Stacked on: #257 (feat/aicore-clear-client-secret) → #256 (feat/aicore-transparent-tls)

Neither proxy mode nor destination mode requires a LiteLLM upstream change. Both work with the current public litellm package.

---

What changed

set_aicore_config() now detects the routing mode from environment variables (priority: proxy > destination > direct):

Proxy mode — AICORE_PROXY_URL set

Routes all LiteLLM calls through an external LiteLLM proxy (e.g. ADR 0039):

• Sets litellm.api_base and litellm.api_key (proxy master API key) globally
• Model strings (e.g. sap/<model>) are passed verbatim — no prefix rewrite. LiteLLM routes sap/<model> through the configured api_base natively (aligned with ADR 0039)
• No AI Core credentials written to the process environment
• JWT never reaches the agent process — the proxy holds the OAuth client secret

Env var naming is intentionally AICORE_* (not LITELLM_*) — the SDK interface is vendor-agnostic and stays stable if the underlying proxy implementation changes.

# Deployer injects these; agent code unchanged
AICORE_PROXY_URL=https://litellm-proxy.cluster.svc
AICORE_PROXY_API_KEY=sk-master-xxx

Destination mode — AICORE_DESTINATION_NAME set

Loads AI Core credentials at startup from a named BTP Destination Service destination:

• Uses the existing sap_cloud_sdk.destination client — no new dependencies
• Deployer only needs to inject Destination Service binding credentials into the K8s Secret
• AICORE_CLIENT_SECRET never needs to be in the K8s Secret — it lives in BTP Destination Service
• Combined with _clear_client_secret() (PR feat(aicore): clear AICORE_CLIENT_SECRET after token acquisition (AFSDK-4291) #257), the secret is removed from env after the first successful LiteLLM call
• On AuthenticationError, reload_aicore_credentials() re-fetches fresh credentials from the Destination Service

# Deployer injects these; agent code unchanged
AICORE_DESTINATION_NAME=aicore-instance
# + Destination Service service binding (clientid/clientsecret/url/uri)

End-to-end validated on Kyma managed runtime (AFSDK-4416 ✅).

Direct mode (unchanged)

Neither env var set → existing behaviour: load from mounted K8s secret or env vars. AICORE_TRANSPARENT_TLS still works within direct mode (pending LiteLLM upstream for full end-to-end; see PR #256).

---

Agent code — identical in all modes

# Same regardless of proxy, destination, or direct mode
set_aicore_config()
response = completion(model="sap/gpt-4o", messages=[{"role": "user", "content": "Hello"}])

---

Security coverage

Threat	Proxy mode	Destination mode	Direct mode
CLIENT_SECRET in K8s Secret	✅ not needed	✅ not needed	❌ required
CLIENT_SECRET in process env	✅ never	✅ cleared after first call (#257)	✅ cleared after first call (#257)
JWT in agent process memory	✅ never (proxy holds it)	❌ agent receives JWT	❌ agent receives JWT
LiteLLM upstream change required	✅ no	✅ no	⚠️ yes (for transparent TLS)
Zero agent code changes	✅	✅	✅

---

Tests

New unit tests:

• TestSetAICoreConfigProxyMode (6 tests) — mode detection, litellm globals, precedence, filtering still applied
• TestSetAICoreConfigDestinationMode (9 tests) — URL extraction, credentials, resource group, error cases

Full suite: 156 passed, 4 skipped (integration tests requiring real BTP).

---

Related

• AFSDK-4414 — Option 3 BLI
• AFSDK-4416 — E2E validation BLI (Destination mode — validated ✅ on Kyma auto-doc-dev-eu12)
• HASI2026203 (CVE 9.9)
• ADR 0039 (LiteLLM proxy, CAD)
• Stacked on: feat(aicore): clear AICORE_CLIENT_SECRET after token acquisition (AFSDK-4291) #257 (clear CLIENT_SECRET) → feat(aicore): transparent TLS mode and reactive credential reload #256 (transparent TLS + reactive reload)