fix(backend): keep Developer API conversation reads under one shared ceiling

Splitting conversation list and detail reads into separately tunable policies
(#8713) gave each route its own bucket, so a single API key can make 60 list
reads *and* 60 detail reads per hour where it previously made 60 in total.

The practical exposure delta is small -- detail reads return one conversation
each, ~1% of what the list endpoint's 100-record pages already allow, and the
polling vector from the original incident is still capped at 60/hr. The reason
to fix it is structural: nothing bounds the policy set, so every future
dev:conversation_*_read policy silently raises the aggregate again.

Add a "dev:conversation_reads_total" policy that every conversation read charges
before its per-route budget. The aggregate returns to 60/hr while list, detail
and transcript budgets stay independently tunable underneath it, which also
settles the review thread asking why detail was given the same value as list.

Costs one extra Redis round trip on the two conversation read routes; the
existing transcript sub-budget already charges two buckets on the same request.

The added test drives both routes in alternation and asserts the aggregate, not
a per-route budget, is what rejects the caller. It fails on the prior wiring
with "120 != 60".

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: RatnamOjha

backend/dependencies.py

@@ -339,12 +339,29 @@ def _require_conversations_read_scope(auth: ApiKeyAuth):
         )
 
 
+async def _check_conversation_read_budgets_async(
+    *,
+    request: Optional[Request],
+    auth: ApiKeyAuth,
+    route_policy_name: str,
+) -> None:
+    """Charge a conversation read against the shared ceiling, then its per-route budget.
+
+    The shared ceiling is checked first so sustained polling is rejected on the
+    aggregate budget regardless of which read route it targets. Without it, adding a
+    per-route policy would hand each key a fresh bucket and raise the total number of
+    conversation reads it can make -- the opposite of what these limits are for.
+    """
+    await _check_dev_api_key_rate_limit_async(request=request, auth=auth, policy_name="dev:conversation_reads_total")
+    await _check_dev_api_key_rate_limit_async(request=request, auth=auth, policy_name=route_policy_name)
+
+
 async def get_auth_with_conversations_read(
     auth: ApiKeyAuth = Depends(get_api_key_auth),
     request: Request = None,
 ) -> ApiKeyAuth:
     _require_conversations_read_scope(auth)
-    await _check_dev_api_key_rate_limit_async(request=request, auth=auth, policy_name="dev:conversations_read")
+    await _check_conversation_read_budgets_async(request=request, auth=auth, route_policy_name="dev:conversations_read")
     return auth
 
 
@@ -353,7 +370,9 @@ async def get_auth_with_conversation_detail_read(
     request: Request = None,
 ) -> ApiKeyAuth:
     _require_conversations_read_scope(auth)
-    await _check_dev_api_key_rate_limit_async(request=request, auth=auth, policy_name="dev:conversation_detail_read")
+    await _check_conversation_read_budgets_async(
+        request=request, auth=auth, route_policy_name="dev:conversation_detail_read"
+    )
     return auth
 
 

backend/tests/unit/test_dependency_async_boundaries.py

@@ -282,7 +282,10 @@ async def exercise() -> None:
         assert policies == [
             'mcp:memories_read',
             'mcp:memories_write',
+            # Each conversation read charges the shared ceiling before its per-route budget.
+            'dev:conversation_reads_total',
             'dev:conversations_read',
+            'dev:conversation_reads_total',
             'dev:conversation_detail_read',
             'dev:conversations',
             'dev:memories_read',

backend/tests/unit/test_rate_limiting.py

@@ -489,6 +489,7 @@ def test_all_router_policies_exist(self):
             "goals:advice",
             "goals:extract",
             "dev:conversations",
+            "dev:conversation_reads_total",
             "dev:conversations_read",
             "dev:conversation_detail_read",
             "dev:conversation_transcript_read",
@@ -561,6 +562,7 @@ def test_developer_dependencies_have_read_rate_limits(self):
         for policy in [
             "dev:memories_read",
             "dev:action_items_read",
+            "dev:conversation_reads_total",
             "dev:conversations_read",
             "dev:conversation_detail_read",
             "dev:conversation_transcript_read",
@@ -592,6 +594,62 @@ def test_developer_conversation_reads_emit_sanitized_audit_logs(self):
         self.assertNotIn("request.headers.get('Authorization'", dependencies_source)
         self.assertNotIn('request.headers.get("Authorization"', dependencies_source)
 
+    def test_conversation_reads_share_an_aggregate_ceiling(self):
+        """Per-route read policies must not raise the total reads a key can make.
+
+        Before list and detail were split into separate policies they shared one
+        60/hr bucket. Giving detail its own 60/hr policy without a shared ceiling
+        would let one key make 120 conversation reads an hour -- a loosening of the
+        exact limit #8713 asked to tighten. The shared ceiling is what prevents that,
+        so this drives both routes and asserts the aggregate, not the per-route, cap
+        is what stops the caller.
+        """
+        dependencies = importlib.import_module("dependencies")
+
+        auth = dependencies.ApiKeyAuth(
+            uid="uid1",
+            scopes=["conversations:read"],
+            app_id="test-app",
+            key_id="test-key",
+        )
+
+        counters: dict[str, int] = {}
+
+        def counting_limiter(*, prefix, uid, app_id, key_id, policy_name):
+            max_requests, _window = RATE_POLICIES[policy_name]
+            counters[policy_name] = counters.get(policy_name, 0) + 1
+            if counters[policy_name] > max_requests:
+                raise HTTPException(status_code=429, detail="Rate limit exceeded")
+
+        async def drive() -> int:
+            served = 0
+            # Alternate routes so neither per-route bucket can be what stops us.
+            for i in range(500):
+                dep = (
+                    dependencies.get_auth_with_conversations_read
+                    if i % 2 == 0
+                    else dependencies.get_auth_with_conversation_detail_read
+                )
+                try:
+                    await dep(auth)
+                except HTTPException as exc:
+                    self.assertEqual(exc.status_code, 429)
+                    break
+                served += 1
+            return served
+
+        with patch.object(dependencies, "check_api_key_rate_limit", counting_limiter):
+            served = asyncio.run(drive())
+
+        umbrella_max, _window = RATE_POLICIES["dev:conversation_reads_total"]
+        split_total = RATE_POLICIES["dev:conversations_read"][0] + RATE_POLICIES["dev:conversation_detail_read"][0]
+
+        self.assertEqual(served, umbrella_max)
+        self.assertLess(served, split_total, "per-route budgets must not sum into a higher effective ceiling")
+        # The shared ceiling, not a per-route budget, is what rejected the caller.
+        self.assertLessEqual(counters["dev:conversations_read"], RATE_POLICIES["dev:conversations_read"][0])
+        self.assertLessEqual(counters["dev:conversation_detail_read"], RATE_POLICIES["dev:conversation_detail_read"][0])
+
     def test_developer_rate_limit_failures_log_without_request(self):
         dependencies = importlib.import_module("dependencies")
         auth = dependencies.ApiKeyAuth(

backend/utils/rate_limit_config.py

@@ -118,6 +118,12 @@
     # MCP API-key contexts are keyed by app/key identity when available.
     "dev:memories_read": (120, 3600),
     "dev:action_items_read": (120, 3600),
+    # Conversation reads are limited in two tiers. Every conversation read consumes
+    # the shared "reads_total" ceiling plus its per-route budget, so splitting list
+    # and detail into separately tunable policies cannot raise the aggregate number
+    # of conversation reads one key can make. Transcript reads consume a third,
+    # stricter bucket on top of the other two.
+    "dev:conversation_reads_total": (60, 3600),
     "dev:conversations_read": (60, 3600),
     "dev:conversation_detail_read": (60, 3600),
     "dev:conversation_transcript_read": (25, 3600),