Document ASGI-only requirement for BedrockAgentCoreContext

[jariy17]

Summary

BedrockAgentCoreContext uses ContextVar for storing request-scoped sensitive data (workload access tokens, OAuth2 callback URLs, authorization headers). While this is safe for ASGI web frameworks, it creates a critical security vulnerability if used with WSGI frameworks.

Problem

ContextVar isolation behavior:

• ✅ ASGI frameworks (Starlette, FastAPI, Quart): Automatically isolated per async task (each HTTP request)
• ❌ WSGI frameworks (Flask, Django WSGI): NOT automatically isolated - threads are reused across requests

Security risk with WSGI:

# WSGI thread pool scenario
# Request A (Thread 1) → BedrockAgentCoreContext.set_workload_access_token("USER_A_TOKEN")
# Request B (Thread 1) → BedrockAgentCoreContext.get_workload_access_token() 
#                     → Returns "USER_A_TOKEN" ❌ (LEAKED!)

This causes:

• Token leakage between requests
• Authorization bypass vulnerabilities
• Data access from one user by another

Current Status

The AgentCore SDK correctly uses Starlette (ASGI), making it safe. However, there's no documentation warning against using BedrockAgentCoreContext in non-ASGI environments.

Recommendation

Add documentation to explicitly state:

1. In src/bedrock_agentcore/runtime/context.py docstring:

   • BedrockAgentCoreContext is designed for ASGI web frameworks only
   • Using with WSGI frameworks creates security vulnerabilities
   • ContextVars rely on async task isolation, not thread isolation

2. In README or main documentation:

   • Note that the SDK requires ASGI (already uses Starlette)
   • If users want to integrate with Flask/WSGI, they need alternative approaches (Flask's g object, thread-local storage with manual cleanup)

3. Consider adding a runtime check (optional):

   • Detect if running in WSGI context
   • Emit warning about unsafe usage

References

• BedrockAgentCoreContext implementation: src/bedrock_agentcore/runtime/context.py:16-21
• Context initialization in request handler: src/bedrock_agentcore/runtime/app.py:299-347
• Python ContextVar documentation: https://docs.python.org/3/library/contextvars.html

Impact

• Severity: High (security vulnerability if misused)
• Likelihood: Low (SDK uses Starlette, but users might try to reuse context pattern)
• Action: Documentation update to prevent misuse