fix(templates): unwrap SecretStr only on persistence path, not API responses

PR #744 stopped the SecretStr-not-JSON-serializable crash on
POST/PUT /templates by switching the configurations dump to
mode="json". That stops the crash, but Pydantic's default JSON
serialization for SecretStr is the masked form ("**********") —
silently corrupting the persisted token. At call time the loaded
template then sends `Authorization: Bearer **********` to the
upstream MCP / HTTP endpoint, which fails authentication.

Fix is in two parts:

1. HttpAuthConfig.field_serializer (template/types.py)
   Reveals the underlying string for the three SecretStr fields
   (token, password, api_key_value) **only when** model_dump is
   invoked with context={"reveal_secrets": True}. Without the
   context flag the serializer falls back to the masked
   "**********" form. So:
     - Persistence paths (create_template_handler,
       replace_template_handler) pass the context and write the real
       value (typically a `{credential_name}` placeholder resolved
       per call from the credentials table).
     - All other JSON serialization paths — notably FastAPI response
       encoding for GET /templates/{id} and the PUT response — see
       no context, fall through to the masked form, and so do not
       leak literal tokens that an operator may have embedded
       directly. This addresses the AI review note on the original
       PR (mask_template_secrets() only masks template.secrets, not
       template.configurations, so the Pydantic-level mask was the
       only guard for configurations.mcp.servers[*].auth.token in
       API responses).

2. template/cache.py — also passes reveal_secrets context
   The Redis L2 template cache calls model_dump_json() to populate
   itself. Without the context flag it would serialize the auth
   token as "**********" and on cache HIT reconstruct the template
   with auth.token = SecretStr("**********") — runtime would then
   send `Authorization: Bearer **********` to the MCP server.
   Reproduced live in chat: turn 1 (cache miss) succeeded because
   MCP setup ran before the cache write, but turn 2+ hit the
   poisoned cache and returned `web_search_exa error (401):
   Invalid API key` from Exa. The cache is internal/private; the
   masking only belongs in API responses, where the lack of context
   preserves it.

mode="python" (the default) keeps the SecretStr instance, so
in-memory access via `.get_secret_value()` on the runtime path is
unaffected.

Verified end-to-end against the running local server, six cases:

  Persistence + API response (HTTP layer)
  1. Placeholder template POST -> DB has "{exa_api_key}" literal,
     GET API response auth.token = "**********".
  2. Literal-token template POST with token="sk-LITERAL-LEAK-CANARY-12345"
     -> DB has the literal canary, GET API response auth.token =
     "**********", canary string occurs zero times in the response
     body (full-body grep).
  3. PUT replace path: PUT with token="sk-PUT-CANARY-67890" -> DB
     has the new literal canary, PUT response masked, canary occurs
     zero times in response body.
  4. Test rows cleaned up.

  Redis cache + chat runtime (cache.py fix)
  5. Busted local Redis cache for chat-direct-claude template, ran
     two-turn chat session via the demo session API. Both turns
     show `auth-fingerprint=resolved-len=43-tail=0556fe` (the real
     Exa key is 36 chars, so "Bearer " + 36 = 43; tail matches the
     real key suffix). Cache HIT (turn 2) preserves the placeholder.
  6. Turn 2 prompt asked the LLM to web-search Strait of Hormuz
     news; web_search_exa was invoked, returned real Reuters /
     India trade news content with 7 cited URLs in the assistant
     reply; zero `Invalid API key` strings in the response.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: swaroopvarma2359

app/ai/voice/agents/breeze_buddy/template/cache.py

@@ -63,9 +63,18 @@ async def get_template_by_id_cached(template_id: str) -> Optional[TemplateModel]
         return None
 
     try:
+        # ``reveal_secrets`` lets HttpAuthConfig's field_serializer (see
+        # template/types.py) emit the underlying string for
+        # ``token``/``password``/``api_key_value`` rather than the masked
+        # ``"**********"`` form. Without it, cache writes would store a
+        # masked auth value, and the next cache HIT would reconstruct
+        # ``SecretStr("**********")`` — runtime would then send
+        # ``Authorization: Bearer **********`` to the upstream server.
+        # The Redis cache is internal/private; the masking only belongs
+        # in API responses, where the lack of context preserves it.
         await redis.setex(
             cache_key,
-            template.model_dump_json(),
+            template.model_dump_json(context={"reveal_secrets": True}),
             ttl_seconds=CACHE_TTL_SECONDS,
         )
         logger.debug(f"template cache populated: {template_id}")

app/ai/voice/agents/breeze_buddy/template/types.py

@@ -10,6 +10,8 @@
     ConfigDict,
     Field,
     SecretStr,
+    SerializationInfo,
+    field_serializer,
     model_validator,
 )
 
@@ -1050,6 +1052,28 @@ class HttpAuthConfig(BaseModel):
     api_key_name: Optional[str] = None  # Header name for API key
     api_key_value: Optional[SecretStr] = None  # API key value
 
+    # Templates are persisted to Postgres as JSON. Pydantic's default
+    # JSON serialization for SecretStr produces the masked form
+    # ("**********"), which silently corrupts the stored value — the
+    # template would then send `Authorization: Bearer **********` at
+    # call time. We unmask **only** when an explicit
+    # ``context={"reveal_secrets": True}`` flag is passed to model_dump
+    # (the create/replace handlers do this on the persistence path).
+    # All other JSON serialization paths — notably FastAPI response
+    # encoding for GET / PUT — see no context, fall through to the
+    # masked form, and so do not leak literal tokens that an operator
+    # may have embedded directly (vs. the intended
+    # ``{credential_name}`` placeholder pattern).
+    @field_serializer("token", "password", "api_key_value", when_used="json")
+    def _reveal_secret(
+        self, value: Optional[SecretStr], info: SerializationInfo
+    ) -> Optional[str]:
+        if value is None:
+            return None
+        if info.context and info.context.get("reveal_secrets"):
+            return value.get_secret_value()
+        return "**********"
+
 
 class HttpRequestConfig(BaseModel):
     """Complete HTTP request configuration for hooks and global functions.

app/api/routers/breeze_buddy/templates/handlers.py

@@ -111,13 +111,19 @@ async def create_template_handler(
         now = datetime.now(timezone.utc)
 
         # Build configurations dict from the ConfigurationModel.
-        # mode="json" unwraps SecretStr fields (e.g. mcp.servers[*].auth.token)
-        # to their string value so the downstream json.dumps in
-        # ``create_template`` doesn't choke on a SecretStr instance.
+        # mode="json" + reveal_secrets context unwraps SecretStr fields
+        # (e.g. mcp.servers[*].auth.token) to their underlying string so
+        # the downstream json.dumps in ``create_template`` writes the
+        # real value (typically a ``{credential_name}`` placeholder).
+        # Without the context flag, HttpAuthConfig's serializer falls
+        # back to the masked "**********" form, which is what we want
+        # everywhere except this persistence path.
         configurations = None
         if template_data.configurations:
             configurations = template_data.configurations.model_dump(
-                exclude_none=True, mode="json"
+                exclude_none=True,
+                mode="json",
+                context={"reveal_secrets": True},
             )
 
         template = await create_template(
@@ -404,13 +410,19 @@ async def replace_template_handler(
         now = datetime.now(timezone.utc)
 
         # Build configurations dict from the ConfigurationModel.
-        # mode="json" unwraps SecretStr fields (e.g. mcp.servers[*].auth.token)
-        # to their string value so the downstream json.dumps in
-        # ``replace_template`` doesn't choke on a SecretStr instance.
+        # mode="json" + reveal_secrets context unwraps SecretStr fields
+        # (e.g. mcp.servers[*].auth.token) to their underlying string so
+        # the downstream json.dumps in ``replace_template`` writes the
+        # real value (typically a ``{credential_name}`` placeholder).
+        # Without the context flag, HttpAuthConfig's serializer falls
+        # back to the masked "**********" form, which is what we want
+        # everywhere except this persistence path.
         configurations = None
         if template_data.configurations:
             configurations = template_data.configurations.model_dump(
-                exclude_none=True, mode="json"
+                exclude_none=True,
+                mode="json",
+                context={"reveal_secrets": True},
             )
 
         # Merge secrets: preserve **** values from existing, update real values