fix(mcp): fall back to live Clerk lookup when cached org_plan is stale

The MCP path was reading org_plan from a Setting populated only by the
subscription.created/updated/active webhook. When that webhook never
fires (org upgraded before the handler shipped, delivery failed, or the
Clerk plan slug doesn't match the literal "pro" key in RATE_LIMITS),
paid orgs get blocked with "MCP requires a Pro or Business plan" even
though their JWT-based dashboard correctly shows them as Pro.

Fix: add resolve_org_plan() in app/core/plans.py that:
- Returns the cached Setting immediately when it's a known paid plan
  (fast path, zero API calls)
- Falls back to clerk.organizations.get_billing_subscription() to read
  the live subscription state, then writes the corrected slug back to
  the Setting so future calls hit the fast path
- Throttles live re-checks to once per 60s per org so a non-paid
  caller hammering MCP can't drive Clerk API spend
- Survives Clerk API failures by returning the cached value (or
  free_org)

Use the resolver in two places:
- mcp/server.py _resolve_org() — the auth gate that was rejecting
  legitimate Pro orgs
- get_plan_limits_for_org() in plans.py — same drift can affect node
  registration and any other API-key-authed endpoint reading plan
  limits

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

Author: Sbussiso

backend/app/core/plans.py

@@ -7,6 +7,11 @@
   - business  (Business — $49/mo)
 """
 
+import logging
+import time
+
+logger = logging.getLogger(__name__)
+
 PLAN_LIMITS = {
     "free_org": {
         "max_cameras": 2,
@@ -22,22 +27,92 @@
     },
 }
 
+# Slugs we trust without re-checking against Clerk.
+PAID_PLAN_SLUGS = frozenset({"pro", "business"})
+
+# Min seconds between consecutive live Clerk lookups for the same org.
+# Prevents non-paid callers from generating excessive Clerk API traffic
+# when they hit the MCP gate repeatedly.
+_RESOLVE_THROTTLE_SECONDS = 60.0
+_last_resolve_at: dict[str, float] = {}
+
 
 def get_plan_limits(plan: str) -> dict:
     """Return the limits dict for a plan slug. Falls back to free tier."""
     return PLAN_LIMITS.get(plan, PLAN_LIMITS["free_org"])
 
 
+def resolve_org_plan(db, org_id: str) -> str:
+    """Return the current plan slug for an org, with a Clerk fallback.
+
+    Read order:
+      1. Cached `Setting(org_plan)` — populated by the Clerk webhook
+         handler in app/api/webhooks.py. If the value is a recognized
+         paid plan, return immediately (fast path, no API call).
+      2. Live `clerk.organizations.get_billing_subscription()` — fixes
+         orgs whose subscription webhook never fired (e.g. they
+         upgraded before the handler shipped, delivery failed, or the
+         dashboard plan name produced a slug that didn't match a key
+         in PLAN_LIMITS). The fresh slug is written back to the
+         Setting so future calls hit the fast path.
+
+    Live lookups for the same org are throttled to once per 60 seconds
+    so a free-tier caller hammering MCP can't drive Clerk API spend.
+    """
+    from app.models.models import Setting
+    from app.core.clerk import clerk
+
+    cached = Setting.get(db, org_id, "org_plan", "")
+    if cached in PAID_PLAN_SLUGS:
+        return cached
+
+    # Throttle live re-checks per org.
+    now = time.monotonic()
+    if now - _last_resolve_at.get(org_id, 0.0) < _RESOLVE_THROTTLE_SECONDS:
+        return cached or "free_org"
+    _last_resolve_at[org_id] = now
+
+    try:
+        sub = clerk.organizations.get_billing_subscription(organization_id=org_id)
+    except Exception:
+        logger.warning(
+            "Live Clerk plan lookup failed for org %s — returning cached value %r",
+            org_id, cached, exc_info=True,
+        )
+        return cached or "free_org"
+
+    # Mirror the webhook handler's logic: take the first active item's plan slug.
+    live_slug = "free_org"
+    for item in (sub.subscription_items or []):
+        status = getattr(item, "status", None)
+        plan = getattr(item, "plan", None)
+        if status == "active" and plan and getattr(plan, "slug", None):
+            live_slug = plan.slug
+            break
+
+    if live_slug != cached:
+        Setting.set(db, org_id, "org_plan", live_slug)
+        try:
+            db.commit()
+            logger.info(
+                "Resolved org %s plan from Clerk: cached=%r → live=%r",
+                org_id, cached, live_slug,
+            )
+        except Exception:
+            db.rollback()
+            logger.exception("Failed to persist resolved plan for org %s", org_id)
+
+    return live_slug
+
+
 def get_plan_limits_for_org(db, org_id: str) -> dict:
     """Look up an org's plan from the database and return its limits.
 
     Used by endpoints that authenticate via API key (e.g. node registration)
-    where JWT claims are not available.  The plan is stored as a Setting
-    by the Clerk webhook handler whenever a subscription changes.
+    where JWT claims are not available.  Falls back to a live Clerk lookup
+    if the cached Setting is stale or missing — see ``resolve_org_plan``.
     """
-    from app.models.models import Setting
-
-    plan = Setting.get(db, org_id, "org_plan", "free_org")
+    plan = resolve_org_plan(db, org_id)
     limits = get_plan_limits(plan)
     # Attach the plan slug so callers can show a display name
     return {**limits, "_plan": plan}

backend/app/mcp/server.py

@@ -137,8 +137,11 @@ def _resolve_org(headers: dict | None) -> tuple[str, Session]:
             db.close()
             raise ToolError("Unauthorized: invalid or revoked API key")
 
-        # Look up org plan and enforce access + rate limit
-        plan = Setting.get(db, mcp_key.org_id, "org_plan", "free_org")
+        # Look up org plan and enforce access + rate limit. Uses the
+        # resolver so orgs whose subscription webhook never landed
+        # still get checked against the live Clerk subscription state.
+        from app.core.plans import resolve_org_plan
+        plan = resolve_org_plan(db, mcp_key.org_id)
         limit = RATE_LIMITS.get(plan)
         if limit is None:
             db.close()
@@ -649,7 +652,8 @@ def get_system_status() -> dict:
         online_cameras = sum(1 for c in cameras if c.effective_status != "offline")
         online_nodes = sum(1 for n in nodes if n.effective_status not in ("offline", "pending"))
 
-        plan = Setting.get(db, org_id, "org_plan", "free_org")
+        from app.core.plans import resolve_org_plan
+        plan = resolve_org_plan(db, org_id)
 
         return {
             "org_id": org_id,