feat(viewer-context): Restore ViewerContext from JWT in middleware (#112875)

Middleware decodes `X-Viewer-Context` on incoming requests.

- Auth user always wins; header only used when no user is authenticated
- Dual-mode: accepts both JWT (new) and JSON + HMAC signature (legacy)
- Org ID mismatch between header and auth user logged as error
- Parsing logic lives in `viewer_context.py` as
`viewer_context_from_header()`
- Verification keys in `_get_verification_keys()` — currently just
`SEER_API_SHARED_SECRET`

Depends on #112765.

---------

Co-authored-by: Claude Opus 4 <noreply@anthropic.com>

Author: gricha

src/sentry/middleware/viewer_context.py

@@ -1,25 +1,36 @@
 from __future__ import annotations
 
+import logging
 from collections.abc import Callable
 
 from django.conf import settings
 from django.http.request import HttpRequest
 from django.http.response import HttpResponseBase
 
 from sentry import options
-from sentry.viewer_context import ActorType, ViewerContext, viewer_context_scope
+from sentry.viewer_context import (
+    ActorType,
+    ViewerContext,
+    viewer_context_from_header,
+    viewer_context_scope,
+)
+
+logger = logging.getLogger(__name__)
 
 
 def ViewerContextMiddleware(
     get_response: Callable[[HttpRequest], HttpResponseBase],
 ) -> Callable[[HttpRequest], HttpResponseBase]:
-    """Set :class:`ViewerContext` for every request after authentication.
+    """Set :class:`ViewerContext` for every request.
+
+    Placed after ``AuthenticationMiddleware``. Authenticated user always
+    takes precedence; ``X-Viewer-Context`` header is only used when
+    there is no authenticated *user* (service-to-service calls that
+    authenticate via HMAC but have no user session, e.g. Seer → Sentry).
 
-    Must be placed **after** ``AuthenticationMiddleware`` so that
-    ``request.user`` and ``request.auth`` are already populated.
+    Accepts both JWT and legacy JSON + HMAC signature formats.
 
-    Gated by the ``viewer-context.enabled`` option (FLAG_NOSTORE).
-    Set via deploy config; requires restart to change.
+    Gated by ``viewer-context.enabled`` (FLAG_NOSTORE).
     """
     enabled = options.get("viewer-context.enabled")
 
@@ -33,13 +44,43 @@ def ViewerContextMiddleware_impl(request: HttpRequest) -> HttpResponseBase:
         if request.path_info.startswith(settings.ANONYMOUS_STATIC_PREFIXES):
             return get_response(request)
 
-        ctx = _viewer_context_from_request(request)
+        request_ctx = _viewer_context_from_request(request)
+        jwt_ctx = _viewer_context_from_jwt_header(request)
+
+        if jwt_ctx is not None and request_ctx.user_id is not None:
+            # Authenticated user takes precedence.
+            if (
+                jwt_ctx.organization_id is not None
+                and request_ctx.organization_id is not None
+                and jwt_ctx.organization_id != request_ctx.organization_id
+            ):
+                logger.error(
+                    "viewer_context.jwt_request_mismatch",
+                    extra={
+                        "jwt_org_id": jwt_ctx.organization_id,
+                        "request_org_id": request_ctx.organization_id,
+                    },
+                )
+            ctx = request_ctx
+        elif jwt_ctx is not None:
+            ctx = jwt_ctx
+        else:
+            ctx = request_ctx
+
         with viewer_context_scope(ctx):
             return get_response(request)
 
     return ViewerContextMiddleware_impl
 
 
+def _viewer_context_from_jwt_header(request: HttpRequest) -> ViewerContext | None:
+    header_value = request.META.get("HTTP_X_VIEWER_CONTEXT")
+    if not header_value:
+        return None
+    signature = request.META.get("HTTP_X_VIEWER_CONTEXT_SIGNATURE")
+    return viewer_context_from_header(header_value, signature)
+
+
 def _viewer_context_from_request(request: HttpRequest) -> ViewerContext:
     user = request.user
     auth = getattr(request, "auth", None)

src/sentry/viewer_context.py

@@ -5,13 +5,18 @@
 import dataclasses
 import enum
 import hashlib
+import hmac
+import logging
 import time
 from collections.abc import Generator
 from typing import TYPE_CHECKING, Any
 
 import jwt as pyjwt
+import orjson
 from django.conf import settings
 
+logger = logging.getLogger(__name__)
+
 if TYPE_CHECKING:
     from sentry.auth.services.auth import AuthenticatedToken
 
@@ -103,6 +108,8 @@ def get_viewer_context() -> ViewerContext | None:
 # ---------------------------------------------------------------------------
 
 _JWT_STANDARD_CLAIMS = frozenset({"iat", "exp", "iss", "aud", "nbf", "jti", "sub"})
+# JWT header field identifying which key was used for signing (RFC 7515 §4.1.4).
+_JWT_KEY_ID_HEADER = "kid"
 
 
 def _key_id(key: str) -> str:
@@ -114,8 +121,8 @@ def _key_id(key: str) -> str:
     return hashlib.sha256(key.encode("utf-8")).hexdigest()[:8]
 
 
-def _get_jwt_secret(key: str | None = None) -> str:
-    """Return the symmetric key to use for JWT signing/verification.
+def _get_signing_key(key: str | None = None) -> str:
+    """Return the key to use for JWT signing.
 
     Resolution: explicit *key* → ``SEER_API_SHARED_SECRET``.
 
@@ -132,14 +139,28 @@ def _get_jwt_secret(key: str | None = None) -> str:
     raise ValueError("No signing key available. Set SEER_API_SHARED_SECRET in settings.")
 
 
+def _get_verification_keys() -> dict[str, str]:
+    """Return a ``{kid: key}`` mapping of all known verification keys.
+
+    Add new service keys here as more services propagate ViewerContext.
+    """
+    keys: dict[str, str] = {}
+
+    seer_secret = getattr(settings, "SEER_API_SHARED_SECRET", "")
+    if seer_secret:
+        keys[_key_id(seer_secret)] = seer_secret
+
+    return keys
+
+
 def encode_viewer_context(
     viewer_context: ViewerContext,
     *,
     key: str | None = None,
     ttl: int | None = None,
 ) -> str:
     """Encode a :class:`ViewerContext` as a signed HS256 JWT."""
-    secret = _get_jwt_secret(key)
+    secret = _get_signing_key(key)
 
     if ttl is None:
         ttl = getattr(settings, "VIEWER_CONTEXT_JWT_TTL", 900)
@@ -152,7 +173,9 @@ def encode_viewer_context(
         "iss": "sentry",
     }
 
-    return pyjwt.encode(payload, secret, algorithm="HS256", headers={"kid": _key_id(secret)})
+    return pyjwt.encode(
+        payload, secret, algorithm="HS256", headers={_JWT_KEY_ID_HEADER: _key_id(secret)}
+    )
 
 
 def decode_viewer_context(
@@ -161,8 +184,22 @@ def decode_viewer_context(
     key: str | None = None,
     leeway: int = 5,
 ) -> ViewerContext:
-    """Decode and verify an HS256 JWT into a :class:`ViewerContext`."""
-    secret = _get_jwt_secret(key)
+    """Decode and verify an HS256 JWT into a :class:`ViewerContext`.
+
+    When *key* is provided it is used directly.  Otherwise all keys
+    from ``_get_verification_keys()`` are tried, kid-matched key first.
+    """
+    if key is not None:
+        secret = key
+    else:
+        keys_by_kid = _get_verification_keys()
+        if not keys_by_kid:
+            raise ValueError("No verification keys available.")
+
+        kid = pyjwt.get_unverified_header(token).get(_JWT_KEY_ID_HEADER)
+        secret = keys_by_kid.get(kid, "") if kid else ""
+        if not secret:
+            raise pyjwt.exceptions.InvalidKeyError(f"No verification key matches kid={kid!r}")
 
     claims = pyjwt.decode(
         token,
@@ -172,10 +209,52 @@ def decode_viewer_context(
         issuer="sentry",
         leeway=leeway,
     )
-    vc_data = {k: v for k, v in claims.items() if k not in _JWT_STANDARD_CLAIMS}
+    vc_data = {ck: cv for ck, cv in claims.items() if ck not in _JWT_STANDARD_CLAIMS}
     return ViewerContext.deserialize(vc_data)
 
 
+def viewer_context_from_header(
+    header_value: str, signature: str | None = None
+) -> ViewerContext | None:
+    """Decode a ViewerContext from ``X-Viewer-Context`` header(s).
+
+    Dual-mode for migration:
+    - JWT (HS256) — new format, self-contained
+    - Raw JSON + ``X-Viewer-Context-Signature`` HMAC — legacy format
+    """
+    if is_jwt_viewer_context(header_value):
+        try:
+            return decode_viewer_context(header_value)
+        except Exception:
+            logger.warning("viewer_context.jwt_decode_failed", exc_info=True)
+            return None
+
+    # Legacy: raw JSON + HMAC signature
+    if signature is not None:
+        return _verify_legacy_viewer_context(header_value, signature)
+
+    return None
+
+
+def _verify_legacy_viewer_context(context_json: str, signature: str) -> ViewerContext | None:
+    """Verify and decode a legacy JSON + HMAC-signed viewer context."""
+    keys_by_kid = _get_verification_keys()
+    context_bytes = context_json.encode("utf-8")
+
+    for key in keys_by_kid.values():
+        computed = hmac.new(key.encode("utf-8"), context_bytes, hashlib.sha256).hexdigest()
+        if hmac.compare_digest(computed, signature):
+            try:
+                data = orjson.loads(context_bytes)
+                return ViewerContext.deserialize(data)
+            except Exception:
+                logger.warning("viewer_context.legacy_decode_failed", exc_info=True)
+                return None
+
+    logger.warning("viewer_context.legacy_signature_mismatch")
+    return None
+
+
 def is_jwt_viewer_context(header_value: str) -> bool:
     """Check whether the header value is a JWT by attempting to read its header.