enhancement: optional strict-mode error envelope sanitization (OpenAI-conformant taxonomy)

[moonming]

Summary

The gateway's error.message field (OpenAI-shape envelope) and error.type field both leak internal-taxonomy / upstream-provider details to the caller. This bleeds across both the streaming and non-streaming paths uniformly, so this is a system-wide pre-existing gap rather than a streaming-specific issue.

Where it leaks

Both paths funnel BridgeError through err.to_string() for error.message and err.error_type() for error.type:

• Non-streaming: crates/aisix-proxy/src/error.rs:127 — ProxyError::envelope() calls self.to_string() which, for ProxyError::Bridge(err), transparently forwards to BridgeError's Display impl. That Display formats include raw upstream body fragments and parser detail:
  • BridgeError::UpstreamStatus { status, message } → "upstream returned HTTP {status}: {message}" — message carries upstream provider error text.
  • BridgeError::UpstreamDecode(s) → "upstream returned an unparseable body: {s}" — s is serde_json parser detail (e.g. "expected value at line 1 column 1").
  • BridgeError::Transport(s) → "transport error: {s}" — s is hyper/reqwest internals.
• Streaming: crates/aisix-proxy/src/chat.rs::build_sse_stream (post-fix(proxy): omit terminal [DONE] when stream terminates abnormally #198) emits the same err.to_string() payload inside the SSE error frame's message field via error_frame_payload(etype, &err.to_string()).

The error.type taxonomy from BridgeError::error_type() (crates/aisix-gateway/src/bridge.rs:109-118) emits upstream_decode_error, transport_error, stream_aborted, config_error — none of which appear in OpenAI's enumerated error.type values. Clients that switch on error.type will hit unknown values.

Why this matters

• Sensitive information bleed: upstream provider error messages can carry account-shape hints, internal model names, prompt-fragment echoes, or rate-limit-policy detail that the gateway should not expose to its own callers.
• Internal taxonomy leak: upstream_decode_error / stream_aborted / config_error reveal aisix-internal failure categorization. Callers should see a stable OpenAI-shape taxonomy.
• Spec deviation: clients that key off the OpenAI taxonomy (e.g. retry policies based on error.type === "rate_limit_error") get unexpected types.

Scope

Affects every endpoint that wraps BridgeError into the wire envelope:

• /v1/chat/completions (streaming + non-streaming)
• /v1/embeddings
• /v1/completions
• /v1/responses (streaming + non-streaming)
• /v1/images/generations
• All of the above when fronted by failover or direct dispatch

Proposed fix

Two parts, both touching crates/aisix-proxy/src/error.rs:

1. Map BridgeError::error_type() to the OpenAI taxonomy at the proxy boundary (not the bridge layer — bridge taxonomy is fine for internal logs / metrics):

   • Timeout → api_error (or new explicit timeout if we want to extend OpenAI)
   • UpstreamStatus/UpstreamDecode/Transport/StreamAborted → api_error
   • Config → server_error

2. Sanitize error.message at the proxy boundary by mapping each BridgeError variant to a generic client-safe string:

   • UpstreamDecode(_) → "upstream returned an unparseable response"
   • Transport(_) → "upstream transport error"
   • Timeout { .. } → "upstream timed out"
   • StreamAborted → "upstream cancelled the response mid-stream"
   • UpstreamStatus { .. } → "upstream returned an error" (status is already conveyed via HTTP code)
   • Config(_) → "gateway misconfiguration"

   Internal logs (via tracing::warn!(error = %err, ...)) keep the rich original detail for operator debugging.

This change must apply uniformly to both the streaming SSE error frame and the non-streaming JSON envelope so the two paths emit identical taxonomy + sanitized messages.

Companion: #153

#153 covers the related case where an output-keyword guardrail leaks the matched literal back to the caller. The fix shape is similar (redact at the wire boundary, keep rich detail in logs) but the source is ProxyError::ContentFiltered rather than ProxyError::Bridge. Worth fixing in the same audit pass.

Surfaced by

Independent audit on PR #198 (HIGH-1 sensitive-info leakage in message, HIGH-2 internal taxonomy leak in type). Recommended both findings be filed as a separate issue rather than widening #198's scope, since the gap pre-exists and spans every endpoint that wraps BridgeError.

[coderabbitai]

🔗 Related PRs

api7/ai-gateway-stash#41 - feat: improve error handle [merged]
api7/ai-gateway-stash#69 - feat: improve provider [merged]
#14 - feat(provider): add new provider gateway types [merged]
#23 - feat(provider): add stream bridged and native implementations [merged]
#37 - feat(proxy): move chat completion to new provider integration [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[moonming]

Triage update — reframed: not a bug, hardening enhancement (LOW priority)

Verified against the de-facto reference implementation in this category. Conclusion: api7-cloud's current behavior actually matches industry practice, so this is a hardening / DX enhancement, not a contract violation.

Evidence — error.message sanitization

The reference router does NOT sanitize upstream message text. The pipeline:

1. Wraps the upstream provider's error body with prefixes (e.g. BadGatewayError: <provider> - <raw upstream JSON or text>) — the raw upstream content passes through.
2. The proxy's outermost handler re-raises with getattr(e, "message", error_msg) — no sanitization layer.
3. The only redaction lever is a global flag redact_messages_in_exceptions (off by default), and it only redacts the prompt-message echo, not the upstream error body.

End result for an upstream 502: error.message like "<reference>.BadGatewayError: OpenAIException - <raw upstream>". So api7-cloud's BridgeError::UpstreamStatus/UpstreamDecode Display strings landing on the wire is the same shape, not a regression.

Evidence — error.type taxonomy

Also custom in the reference:

• "throttling_error" for rate limits (instead of OpenAI's enumerated rate_limit_error)
• "None" literal-string fallback when underlying exception has no .type
• A custom enum with gateway-specific tokens: budget_exceeded, no_db_connection, auth_error, internal_server_error, bad_request_error, validation_error, cache_ping_error, etc.

Some sites do use OpenAI's "invalid_request_error", so usage is mixed — but it's not a strict OpenAI-conformant taxonomy. api7-cloud's upstream_decode_error / transport_error / stream_aborted / config_error are conceptually equivalent and equally non-strict.

Why this isn't a security bug

• The leaked content is upstream provider error text, not credentials, secrets, or cross-tenant PII.
• OpenAI's documented error.type set is a guideline, not a strict contract enforced by client SDKs. Production routers in this category routinely emit custom types and verbatim upstream messages; clients tolerate it.
• Hyper internals and serde_json parser strings ("expected value at line 1 column 1") are noise the caller can't act on — that's the real DX/hygiene concern, not a security one.

Audit recommendation (separate from #199)

There IS a narrow security check worth doing as a one-off audit:

Audit BridgeError Display impls for any genuinely sensitive content — gateway's own API keys, internal hostnames, auth tokens. If any of those are embedded in Display strings, that's a true HIGH-severity leak independent of #199's framing.

I'll file that as a separate audit task if the existing Display impls are not already trivially safe.

Recommended fix shape (if pursued)

Opt-in error_sanitization config flag, default passthrough (preserves operator debuggability and matches reference behavior):

[proxy]
error_sanitization = "passthrough"  # default; or "strict"

In strict mode:

• Replace error.message with a generic, variant-keyed string ("Upstream returned an error", "Failed to decode upstream response", "Connection to upstream interrupted").
• Remap error.type to one of the seven OpenAI enumerated values via a static mapping table.
• Keep raw detail in structured logs only.
• README documents that passthrough matches industry practice and strict is for callers who need OpenAI-conformant typing.

This converts #199 from "real bug" framing into a configurable hardening knob — which is the honest characterization given how comparable routers behave.

Disposition

• Severity downgrade: bug → enhancement
• Drop the vulnerability label (the leaked content is not security-sensitive in the cryptographic sense).
• Priority: LOW.
• Pre-req: separate one-off audit on BridgeError Display impls for genuinely sensitive content. If found, that's HIGH and gets its own issue.