superlocalmemory 3.6.13 → 3.6.14

package/src/superlocalmemory/optimize/proxy/_helpers.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import asyncio
+import inspect
 import json
 import logging
 from typing import Any, AsyncIterator, Callable
@@ -22,6 +23,39 @@ _get_running_loop = asyncio.get_running_loop
 
 logger = logging.getLogger("slm.optimize.proxy.helpers")
 
+# Per-callable cache of "does this hook method accept a tenant_id kwarg?".
+# Keyed by id() of the bound method's __func__ so it is stable per hook class.
+_HOOK_TENANT_SUPPORT: dict[int, bool] = {}
+
+
+def _accepts_tenant_id(fn: Callable) -> bool:
+    """Return True if a hook method accepts a ``tenant_id`` keyword argument.
+
+    SECURITY (Stage-9 R1): the original WP-D shim used ``except TypeError`` to
+    detect legacy hooks, but that clause is structurally unable to tell a
+    signature mismatch from a TypeError raised *inside* a tenant-aware hook —
+    so an internal bug silently downgraded an authenticated request onto the
+    shared (tenant-less) path, re-opening cross-tenant disclosure.  We instead
+    probe the signature ONCE (cached): a hook is treated as tenant-aware if it
+    has an explicit ``tenant_id`` parameter or accepts ``**kwargs``.  A
+    tenant-aware hook is NEVER retried without the tenant_id; any error it
+    raises fails open to a cache MISS, never the shared namespace.
+    """
+    target = getattr(fn, "__func__", fn)
+    key = id(target)
+    cached = _HOOK_TENANT_SUPPORT.get(key)
+    if cached is None:
+        try:
+            params = inspect.signature(fn).parameters
+            cached = "tenant_id" in params or any(
+                p.kind == inspect.Parameter.VAR_KEYWORD for p in params.values()
+            )
+        except (ValueError, TypeError):
+            # Builtins / C callables without a signature — assume legacy.
+            cached = False
+        _HOOK_TENANT_SUPPORT[key] = cached
+    return cached
+
 # SEC-M-02 (CWE-400): reject oversized bodies to prevent compression-bomb DoS.
 _MAX_REQUEST_BODY_BYTES = 10 * 1024 * 1024  # 10 MB
 
@@ -76,6 +110,16 @@ _OPENAI_FORWARD_HEADERS = frozenset([
 _GEMINI_NATIVE_FORWARD_HEADERS = frozenset([
     "x-goog-api-key",
     "content-type",
+    "authorization",  # WP-11a: Antigravity ADC/OAuth bearer was dropped; add it back
+])
+
+# WP-11: Vertex AI forward headers — Authorization passed untouched (AC-2).
+# x-goog-user-project required for quota attribution on Vertex calls.
+_VERTEX_FORWARD_HEADERS = frozenset([
+    "authorization",
+    "content-type",
+    "x-goog-api-key",
+    "x-goog-user-project",
 ])
 
 _GEMINI_OPENAI_COMPAT_FORWARD_HEADERS = frozenset([
@@ -98,6 +142,28 @@ def _redact_headers(headers: dict) -> dict:
     }
 
 
+def _derive_tenant_id(provider: str, raw_credential: "str | None") -> "str | None":
+    """Derive a per-tenant isolation key from the raw (un-redacted) credential.
+
+    SECURITY (WP-D): Called at the surface-handler layer BEFORE _redact_headers
+    strips the credential from ProxyRequest.headers.  The derived id is threaded
+    into CacheManager.check() / .store() so that two users sharing the same
+    prompt but using different API keys receive independent cache namespaces.
+
+    Returns None when no credential is present — callers must SKIP caching
+    (never collapse to the default tenant) to prevent cross-tenant disclosure.
+
+    Output: 64-char lowercase hex SHA-256 of ``f"{provider}:{raw_credential}"``.
+    Provider is folded in so anthropic:K and openai:K are distinct tenants even
+    if the literal key string coincidentally matches.
+    """
+    import hashlib as _hashlib
+
+    if not raw_credential:
+        return None
+    return _hashlib.sha256(f"{provider}:{raw_credential}".encode()).hexdigest()
+
+
 def _body_has_tools(body: dict) -> bool:
     tools = body.get("tools")
     return isinstance(tools, list) and len(tools) > 0
@@ -545,25 +611,62 @@ async def capture_passthrough_forward(
     )
 
 
-async def _safe_cache_check(hooks: HookChain, ctx: ProxyRequest) -> CachedResponse:
+async def _safe_cache_check(
+    hooks: HookChain,
+    ctx: ProxyRequest,
+    tenant_id: "str | None" = None,
+) -> CachedResponse:
+    """Invoke cache.check(); fail-open on error.
+
+    SECURITY (WP-D): tenant_id is forwarded to the CacheHook so that the
+    credential-derived namespace is used.  None signals "skip caching" — the
+    cache hook must not collapse to a default tenant for unauthenticated
+    requests.  When tenant_id is None, return an empty miss immediately.
+
+    Backward compat: a genuinely legacy hook (no tenant_id parameter and no
+    **kwargs) is called without the kwarg.  A tenant-aware hook is NEVER
+    downgraded to the tenant-less path — see _accepts_tenant_id (Stage-9 R1).
+    """
+    miss = CachedResponse(hit=False, data=None, cache_key="", ttl_seconds=0)
+    if tenant_id is None:
+        return miss
     try:
-        result = hooks.cache.check(ctx)
-        return result if result is not None else CachedResponse(
-            hit=False, data=None, cache_key="", ttl_seconds=0
-        )
+        if _accepts_tenant_id(hooks.cache.check):
+            result = hooks.cache.check(ctx, tenant_id=tenant_id)
+        else:
+            # Genuine legacy hook — no tenant_id support at all.
+            result = hooks.cache.check(ctx)
+        return result if result is not None else miss
     except Exception as exc:
-        logger.warning("cache.check failed (fail-open): %s", exc)
-        return CachedResponse(hit=False, data=None, cache_key="", ttl_seconds=0)
+        # SECURITY: a tenant-aware hook that errors must fail-open to a MISS,
+        # never be retried on the shared (tenant-less) namespace.
+        logger.warning("cache.check failed (fail-open miss): %s", exc)
+        return miss
 
 
 async def _safe_cache_store(
     hooks: HookChain,
     ctx: ProxyRequest,
     resp: ProviderResponse,
+    tenant_id: "str | None" = None,
 ) -> None:
+    """Invoke cache.store(); fail-open on error.
+
+    SECURITY (WP-D): tenant_id is forwarded.  None means skip (unauthenticated).
+
+    Backward compat: a genuinely legacy hook (no tenant_id parameter and no
+    **kwargs) is called without the kwarg.  A tenant-aware hook is NEVER
+    downgraded to the tenant-less path — see _accepts_tenant_id (Stage-9 R1).
+    """
+    if tenant_id is None:
+        return
     try:
-        hooks.cache.store(ctx, resp)
+        if _accepts_tenant_id(hooks.cache.store):
+            hooks.cache.store(ctx, resp, tenant_id=tenant_id)
+        else:
+            hooks.cache.store(ctx, resp)
     except Exception as exc:
+        # SECURITY: never retry a tenant-aware hook without tenant_id.
         logger.warning("cache.store failed (fail-open): %s", exc)
 
 

package/src/superlocalmemory/optimize/proxy/anthropic_surface.py

@@ -15,6 +15,7 @@ from superlocalmemory.optimize.proxy._helpers import (
     _MAX_REQUEST_BODY_BYTES,
     _body_has_tools,
     _build_forward_headers,
+    _derive_tenant_id,
     _fail_open_forward,
     _filter_response_headers,
     _parse_sse_to_json,
@@ -204,6 +205,14 @@ async def handle_messages(proxy: object, request: Request) -> Response:
                 sse_parser=_parse_sse_to_json, is_stream=stream,
             )
 
+        # SECURITY (WP-D): derive tenant BEFORE _redact_headers strips the key.
+        # x-api-key is the primary Anthropic credential; fall back to authorization.
+        _raw_key = (
+            request.headers.get("x-api-key")
+            or request.headers.get("authorization")
+        )
+        _tenant_id = _derive_tenant_id("anthropic", _raw_key)
+
         ctx = ProxyRequest(
             provider="anthropic",
             method="POST",
@@ -225,7 +234,7 @@ async def handle_messages(proxy: object, request: Request) -> Response:
             #    accumulated and stored, return it as a proper SSE stream rather
             #    than forwarding to Anthropic at all.
             if proxy.hooks.cache:
-                cache_result = await _safe_cache_check(proxy.hooks, ctx)
+                cache_result = await _safe_cache_check(proxy.hooks, ctx, tenant_id=_tenant_id)
                 if cache_result and cache_result.hit and cache_result.data:
                     logger.debug(
                         "[%s] streaming cache HIT key=%s",
@@ -261,6 +270,7 @@ async def handle_messages(proxy: object, request: Request) -> Response:
             if proxy.hooks.cache:
                 _hooks = proxy.hooks
                 _ctx = ctx
+                _tid = _tenant_id
                 async def _store_from_sse(sse_bytes: bytes) -> None:
                     parsed = _parse_sse_to_json(sse_bytes)
                     if parsed is None:
@@ -269,7 +279,7 @@ async def handle_messages(proxy: object, request: Request) -> Response:
                         modified=False, body={}, body_bytes=parsed,
                         tokens_before=0, tokens_after=0, strategy="none",
                     )
-                    await _safe_cache_store(_hooks, _ctx, prov)
+                    await _safe_cache_store(_hooks, _ctx, prov, tenant_id=_tid)
                 store_callback = _store_from_sse
 
             return await _stream_and_cache_forward(
@@ -279,7 +289,7 @@ async def handle_messages(proxy: object, request: Request) -> Response:
 
         cache_result = None
         if proxy.hooks.cache:
-            cache_result = await _safe_cache_check(proxy.hooks, ctx)
+            cache_result = await _safe_cache_check(proxy.hooks, ctx, tenant_id=_tenant_id)
             if cache_result.hit and cache_result.data:
                 logger.debug("[%s] cache HIT key=%s", request_id, cache_result.cache_key)
                 await _safe_cache_hit_callbacks(
@@ -315,7 +325,7 @@ async def handle_messages(proxy: object, request: Request) -> Response:
                 modified=False, body={}, body_bytes=resp_bytes,
                 tokens_before=0, tokens_after=0, strategy="none",
             )
-            await _safe_cache_store(proxy.hooks, ctx, _prov_resp)
+            await _safe_cache_store(proxy.hooks, ctx, _prov_resp, tenant_id=_tenant_id)
 
         return Response(
             content=resp_bytes,

package/src/superlocalmemory/optimize/proxy/gemini_surface.py

@@ -38,6 +38,7 @@ from superlocalmemory.optimize.proxy._helpers import (
     _GEMINI_NATIVE_FORWARD_HEADERS,
     _GEMINI_OPENAI_COMPAT_FORWARD_HEADERS,
     _body_has_tools,
+    _derive_tenant_id,
     _fail_open_forward,
     _filter_response_headers,
     _redact_headers,
@@ -259,6 +260,14 @@ async def handle_gemini_native(
                 sse_parser=_parse_gemini_sse_to_json, is_stream=stream,
             )
 
+        # SECURITY (WP-D): derive tenant BEFORE _redact_headers strips the key.
+        # Gemini uses x-goog-api-key; OAuth uses authorization bearer.
+        _raw_key = (
+            request.headers.get("x-goog-api-key")
+            or request.headers.get("authorization")
+        )
+        _tenant_id = _derive_tenant_id("gemini", _raw_key)
+
         ctx = ProxyRequest(
             provider="gemini",
             method="POST",
@@ -279,7 +288,7 @@ async def handle_gemini_native(
         if stream:
             # ── 1. Cache check ──────────────────────────────────────────────
             if proxy.hooks.cache:
-                cache_result = await _safe_cache_check(proxy.hooks, ctx)
+                cache_result = await _safe_cache_check(proxy.hooks, ctx, tenant_id=_tenant_id)
                 if cache_result and cache_result.hit and cache_result.data:
                     logger.debug(
                         "[%s] Gemini native streaming cache HIT key=%s",
@@ -314,6 +323,7 @@ async def handle_gemini_native(
             if proxy.hooks.cache:
                 _hooks = proxy.hooks
                 _ctx = ctx
+                _tid = _tenant_id
 
                 async def _store_from_gemini_sse(sse_bytes: bytes) -> None:
                     parsed = _parse_gemini_sse_to_json(sse_bytes)
@@ -323,7 +333,7 @@ async def handle_gemini_native(
                         modified=False, body={}, body_bytes=parsed,
                         tokens_before=0, tokens_after=0, strategy="none",
                     )
-                    await _safe_cache_store(_hooks, _ctx, prov)
+                    await _safe_cache_store(_hooks, _ctx, prov, tenant_id=_tid)
 
                 store_callback = _store_from_gemini_sse
 
@@ -335,7 +345,7 @@ async def handle_gemini_native(
         # ── Non-streaming path ──────────────────────────────────────────────
         cache_result = None
         if proxy.hooks.cache:
-            cache_result = await _safe_cache_check(proxy.hooks, ctx)
+            cache_result = await _safe_cache_check(proxy.hooks, ctx, tenant_id=_tenant_id)
             if cache_result.hit and cache_result.data:
                 await _safe_cache_hit_callbacks(
                     proxy.hooks, ctx, cache_result.data, tokens_saved=0
@@ -369,7 +379,7 @@ async def handle_gemini_native(
                 modified=False, body={}, body_bytes=resp_bytes,
                 tokens_before=0, tokens_after=0, strategy="none",
             )
-            await _safe_cache_store(proxy.hooks, ctx, prov_resp)
+            await _safe_cache_store(proxy.hooks, ctx, prov_resp, tenant_id=_tenant_id)
 
         return Response(
             content=resp_bytes,
@@ -438,6 +448,13 @@ async def handle_gemini_openai_compat(proxy: object, request: Request) -> Respon
                 sse_parser=_parse_openai_sse_to_json, is_stream=stream,
             )
 
+        # SECURITY (WP-D): derive tenant BEFORE _redact_headers strips the key.
+        _raw_key_compat = (
+            request.headers.get("x-goog-api-key")
+            or request.headers.get("authorization")
+        )
+        _tenant_id_compat = _derive_tenant_id("gemini-openai-compat", _raw_key_compat)
+
         ctx = ProxyRequest(
             provider="gemini-openai-compat",
             method="POST",
@@ -453,7 +470,7 @@ async def handle_gemini_openai_compat(proxy: object, request: Request) -> Respon
         # Cache check
         cache_result = None
         if proxy.hooks.cache:
-            cache_result = await _safe_cache_check(proxy.hooks, ctx)
+            cache_result = await _safe_cache_check(proxy.hooks, ctx, tenant_id=_tenant_id_compat)
             if cache_result.hit and cache_result.data:
                 await _safe_cache_hit_callbacks(
                     proxy.hooks, ctx, cache_result.data, tokens_saved=0
@@ -495,7 +512,7 @@ async def handle_gemini_openai_compat(proxy: object, request: Request) -> Respon
                 modified=False, body={}, body_bytes=resp_bytes,
                 tokens_before=0, tokens_after=0, strategy="none",
             )
-            await _safe_cache_store(proxy.hooks, ctx, prov_resp)
+            await _safe_cache_store(proxy.hooks, ctx, prov_resp, tenant_id=_tenant_id_compat)
 
         return Response(
             content=resp_bytes,

package/src/superlocalmemory/optimize/proxy/openai_surface.py

@@ -24,6 +24,7 @@ from superlocalmemory.optimize.proxy._helpers import (
     _OPENAI_FORWARD_HEADERS,
     _body_has_tools,
     _build_forward_headers,
+    _derive_tenant_id,
     _fail_open_forward,
     _filter_response_headers,
     _redact_headers,
@@ -328,6 +329,10 @@ async def handle_chat_completions(proxy: object, request: Request) -> Response:
                 sse_parser=_parse_openai_sse_to_json, is_stream=stream,
             )
 
+        # SECURITY (WP-D): derive tenant BEFORE _redact_headers strips the key.
+        _raw_key = request.headers.get("authorization")
+        _tenant_id = _derive_tenant_id("openai", _raw_key)
+
         ctx = ProxyRequest(
             provider="openai", method="POST", path="/v1/chat/completions",
             headers=_redact_headers(dict(request.headers)),
@@ -343,7 +348,7 @@ async def handle_chat_completions(proxy: object, request: Request) -> Response:
 
             # 1. Cache check
             if proxy.hooks.cache:
-                cache_result = await _safe_cache_check(proxy.hooks, ctx)
+                cache_result = await _safe_cache_check(proxy.hooks, ctx, tenant_id=_tenant_id)
                 if cache_result and cache_result.hit and cache_result.data:
                     logger.debug(
                         "[%s] OpenAI streaming cache HIT key=%s",
@@ -371,6 +376,7 @@ async def handle_chat_completions(proxy: object, request: Request) -> Response:
             if proxy.hooks.cache:
                 _hooks = proxy.hooks
                 _ctx = ctx
+                _tid = _tenant_id
                 async def _store_from_openai_sse(sse_bytes: bytes) -> None:
                     parsed = _parse_openai_sse_to_json(sse_bytes)
                     if parsed is None:
@@ -379,7 +385,7 @@ async def handle_chat_completions(proxy: object, request: Request) -> Response:
                         modified=False, body={}, body_bytes=parsed,
                         tokens_before=0, tokens_after=0, strategy="none",
                     )
-                    await _safe_cache_store(_hooks, _ctx, prov)
+                    await _safe_cache_store(_hooks, _ctx, prov, tenant_id=_tid)
                 store_callback = _store_from_openai_sse
 
             return await _stream_and_cache_forward(
@@ -390,7 +396,7 @@ async def handle_chat_completions(proxy: object, request: Request) -> Response:
         # --- Non-streaming path ---
         cache_result = None
         if proxy.hooks.cache:
-            cache_result = await _safe_cache_check(proxy.hooks, ctx)
+            cache_result = await _safe_cache_check(proxy.hooks, ctx, tenant_id=_tenant_id)
             if cache_result.hit and cache_result.data:
                 await _safe_cache_hit_callbacks(
                     proxy.hooks, ctx, cache_result.data, 0
@@ -425,7 +431,7 @@ async def handle_chat_completions(proxy: object, request: Request) -> Response:
                 modified=False, body={}, body_bytes=resp_bytes,
                 tokens_before=0, tokens_after=0, strategy="none",
             )
-            await _safe_cache_store(proxy.hooks, ctx, _prov_resp)
+            await _safe_cache_store(proxy.hooks, ctx, _prov_resp, tenant_id=_tenant_id)
 
         return Response(
             content=resp_bytes,

package/src/superlocalmemory/optimize/proxy/server.py

@@ -109,6 +109,9 @@ def build_proxy_router(proxy: ProxyApp) -> APIRouter:
         handle_chat_completions,
         handle_embeddings,
     )
+    from superlocalmemory.optimize.proxy.vertex_surface import (
+        handle_vertex_generative,
+    )
 
     router = APIRouter(tags=["slm-optimize-proxy"])
 
@@ -146,6 +149,14 @@ def build_proxy_router(proxy: ProxyApp) -> APIRouter:
     async def gemini_openai_models_route(request: Request) -> Response:
         return await handle_gemini_openai_compat(proxy, request)
 
+    # WP-11: Vertex AI passthrough — must be registered AFTER exact /v1/* routes
+    # to avoid shadowing /v1/messages, /v1/chat/completions, /v1/embeddings, etc.
+    # FastAPI resolves routes in registration order; the exact routes above are
+    # declared before this catch-path, so there is no shadowing.
+    @router.post("/v1/projects/{vertex_path:path}")
+    async def vertex_route(request: Request, vertex_path: str) -> Response:
+        return await handle_vertex_generative(proxy, request, vertex_path)
+
     return router
 
 

package/src/superlocalmemory/optimize/proxy/vertex_surface.py

@@ -0,0 +1,246 @@
+"""vertex_surface.py — Vertex AI passthrough proxy surface (WP-11).
+
+Transparent passthrough: forward Authorization bearer untouched (AC-2),
+cache by body content never by token (SEC), no SSE — always single JSON.
+
+Key design decisions (per LLD §5 STAGE-5 RESOLUTIONS):
+  CRIT-1: Route by FastAPI PATH /v1/projects/{vertex_path:path}, NOT hostname.
+           Upstream host is reconstructed from /locations/{region}/ in the path.
+  CRIT-2: Vertex bodies have no model/messages/system (model in PATH, prompts
+           under 'contents'). The provider=='vertex' branch in CacheManager.build_key
+           extracts these correctly — preventing all-requests-same-key collision.
+  D2: Pin upstream host to https://{location}-aiplatform.googleapis.com from path.
+      IGNORE providers.vertex.base_url — honoring it is an SSRF surface.
+  SECURITY (AC-3): bearer token structurally excluded from cache key, value,
+           logs, and stored ProxyRequest.headers (redacted via _redact_headers).
+
+WP-11a (gemini-native fix) lives in _helpers.py:_GEMINI_NATIVE_FORWARD_HEADERS.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import re
+
+from fastapi.requests import Request
+from fastapi.responses import Response
+
+from superlocalmemory.optimize.proxy._helpers import (
+    _VERTEX_FORWARD_HEADERS,
+    _derive_tenant_id,
+    _fail_open_forward,
+    _filter_response_headers,
+    _redact_headers,
+    _safe_cache_check,
+    _safe_cache_hit_callbacks,
+    _safe_cache_store,
+    capture_passthrough_forward,
+)
+from superlocalmemory.optimize.proxy.capture import capture_enabled
+from superlocalmemory.optimize.proxy.lifecycle import ProviderResponse, ProxyRequest
+
+logger = logging.getLogger("slm.optimize.proxy.vertex")
+
+# ---------------------------------------------------------------------------
+# SSRF guard — LLD §5
+# ---------------------------------------------------------------------------
+
+# Accepts ONLY:
+#   {project}/locations/{location}/publishers/google/models/{model}:{method}
+# Rejects:
+#   - ../ traversal (no dots allowed in segments via character classes)
+#   - unknown methods (countTokens, EXEC, etc.)
+#   - overlong segments
+_VERTEX_PATH_RE = re.compile(
+    r"^(?P<project>[a-zA-Z0-9_\-]{1,63})"
+    r"/locations/(?P<location>[a-z0-9\-]{1,40})"
+    r"/publishers/google/models/(?P<model>[a-zA-Z0-9._\-]{1,128})"
+    r":(?P<method>generateContent|streamGenerateContent)$"
+)
+
+
+def _validate_vertex_path(path: str) -> bool:
+    """Return True iff path matches the Vertex AI path pattern (SSRF guard).
+
+    Rejects ../, traversal characters, unknown methods, and overlong segments.
+    """
+    return bool(_VERTEX_PATH_RE.match(path))
+
+
+def _parse_vertex_path(
+    path: str,
+) -> tuple[str, str, str, str] | None:
+    """Parse a validated Vertex path into (project, location, model, method).
+
+    Returns None on parse failure (caller should return 400).
+    """
+    m = _VERTEX_PATH_RE.match(path)
+    if m is None:
+        return None
+    return (
+        m.group("project"),
+        m.group("location"),
+        m.group("model"),
+        m.group("method"),
+    )
+
+
+def _build_vertex_upstream_url(location: str, full_path: str) -> str:
+    """Build the Vertex upstream URL.
+
+    D2 (LOCKED): pin host to https://{location}-aiplatform.googleapis.com
+    from the path — IGNORE providers.vertex.base_url (honoring it = SSRF).
+    """
+    host = f"https://{location}-aiplatform.googleapis.com"
+    return f"{host}{full_path}"
+
+
+# ---------------------------------------------------------------------------
+# Route handler
+# ---------------------------------------------------------------------------
+
+async def handle_vertex_generative(
+    proxy: object,
+    request: Request,
+    vertex_path: str,
+) -> Response:
+    """Handle POST /v1/projects/{vertex_path:path}.
+
+    Full pipeline: validate → parse → cache check → POST upstream → cache store.
+    Bearer token is NEVER in the cache key (structurally — build_key reads only body).
+    Always returns a single JSON Response — no SSE/StreamingResponse (LLD §1).
+    Fail-open on unexpected exceptions.
+    """
+    request_id = await proxy.next_request_id()
+
+    # ── SSRF guard — validate path BEFORE any upstream contact (AC-3 / LLD §4) ──
+    if not _validate_vertex_path(vertex_path):
+        logger.warning(
+            "[%s] handle_vertex_generative: rejected invalid path=%r (SSRF guard)",
+            request_id, vertex_path,
+        )
+        return Response(
+            content=b'{"error":{"code":400,"message":"Invalid Vertex path",'
+                    b'"status":"INVALID_ARGUMENT"}}',
+            status_code=400,
+            media_type="application/json",
+        )
+
+    parsed = _parse_vertex_path(vertex_path)
+    if parsed is None:
+        # Should not reach here after _validate_vertex_path, but be defensive.
+        logger.error("[%s] handle_vertex_generative: parse failed after validation", request_id)
+        return Response(
+            content=b'{"error":{"code":400,"message":"Path parse error",'
+                    b'"status":"INVALID_ARGUMENT"}}',
+            status_code=400,
+            media_type="application/json",
+        )
+
+    _project, location, _model, _method = parsed
+    upstream_url = _build_vertex_upstream_url(location, str(request.url.path))
+
+    try:
+        body_bytes = await request.body()
+
+        try:
+            body = json.loads(body_bytes) if body_bytes else {}
+        except json.JSONDecodeError:
+            body = {}
+
+        # v3.6.10 shadow-capture: pure passthrough + corpus record.
+        if capture_enabled():
+            return await capture_passthrough_forward(
+                proxy, request,
+                provider="vertex",
+                upstream_url=upstream_url,
+                allowed_headers=_VERTEX_FORWARD_HEADERS,
+                request_id=request_id,
+                model_hint=_model,
+                sse_parser=None,
+                is_stream=False,
+            )
+
+        # SECURITY (AC-3): headers stored in ProxyRequest are redacted.
+        # Bearer token is structurally excluded from the cache key because
+        # build_key reads only body-derived fields (key_builder.py:90-105).
+        #
+        # SECURITY (WP-D): derive tenant BEFORE _redact_headers strips the
+        # bearer token.  Vertex uses Authorization bearer.
+        _raw_key = request.headers.get("authorization")
+        _tenant_id = _derive_tenant_id("vertex", _raw_key)
+
+        ctx = ProxyRequest(
+            provider="vertex",
+            method="POST",
+            path=str(request.url.path),
+            headers=_redact_headers(dict(request.headers)),  # token → [REDACTED]
+            body=body,
+            body_bytes=body_bytes,
+            request_id=request_id,
+            stream=False,
+            has_tools=False,
+        )
+
+        # Build forward headers — Authorization byte-identical (AC-2).
+        fwd_headers = {
+            k: v for k, v in request.headers.items()
+            if k.lower() in _VERTEX_FORWARD_HEADERS
+        }
+
+        # ── Cache check ────────────────────────────────────────────────────
+        cache_result = None
+        if proxy.hooks.cache:
+            cache_result = await _safe_cache_check(proxy.hooks, ctx, tenant_id=_tenant_id)
+            if cache_result and cache_result.hit and cache_result.data:
+                logger.debug(
+                    "[%s] Vertex cache HIT key=%s",
+                    request_id, cache_result.cache_key,
+                )
+                await _safe_cache_hit_callbacks(
+                    proxy.hooks, ctx, cache_result.data, tokens_saved=0
+                )
+                return Response(
+                    content=cache_result.data,
+                    status_code=200,
+                    media_type="application/json",
+                )
+
+        fwd_headers["content-length"] = str(len(body_bytes))
+
+        # ── POST upstream (single JSON — no SSE) ──────────────────────────
+        upstream_resp = await proxy.http_client.post(
+            upstream_url, content=body_bytes, headers=fwd_headers,
+        )
+        resp_bytes = upstream_resp.content
+
+        # ── Cache store on 200 only ────────────────────────────────────────
+        if (
+            upstream_resp.status_code == 200
+            and proxy.hooks.cache
+            and cache_result is not None
+            and cache_result.cache_key
+        ):
+            prov_resp = ProviderResponse(
+                modified=False,
+                body={},
+                body_bytes=resp_bytes,
+                tokens_before=0,
+                tokens_after=0,
+                strategy="none",
+            )
+            await _safe_cache_store(proxy.hooks, ctx, prov_resp, tenant_id=_tenant_id)
+
+        return Response(
+            content=resp_bytes,
+            status_code=upstream_resp.status_code,
+            media_type="application/json",
+            headers=_filter_response_headers(dict(upstream_resp.headers)),
+        )
+
+    except Exception as exc:
+        logger.error(
+            "[%s] handle_vertex_generative exc=%r — fail-open", request_id, exc
+        )
+        return await _fail_open_forward(proxy, request, upstream_url)