Validate property key in breakdown API endpoint (#2686)

* Validate property key in breakdown API endpoint

* Add missing properties

* Do not allow empty custom prop

lib/plausible/stats/breakdown.ex

@@ -9,7 +9,7 @@ defmodule Plausible.Stats.Breakdown do
 
   @event_metrics [:visitors, :pageviews, :events]
   @session_metrics [:visits, :bounce_rate, :visit_duration]
-  @event_props ["event:page", "event:page_match", "event:name"]
+  @event_props Plausible.Stats.Props.event_props()
 
   def breakdown(site, query, "event:goal" = property, metrics, pagination) do
     {event_goals, pageview_goals} =

lib/plausible/stats/props.ex

@@ -1,6 +1,33 @@
 defmodule Plausible.Stats.Props do
   use Plausible.ClickhouseRepo
   import Plausible.Stats.Base
+  @event_props ["event:page", "event:page_match", "event:name", "event:goal"]
+  @session_props [
+    "visit:source",
+    "visit:country",
+    "visit:region",
+    "visit:city",
+    "visit:entry_page",
+    "visit:exit_page",
+    "visit:referrer",
+    "visit:utm_medium",
+    "visit:utm_source",
+    "visit:utm_campaign",
+    "visit:utm_content",
+    "visit:utm_term",
+    "visit:device",
+    "visit:os",
+    "visit:os_version",
+    "visit:browser",
+    "visit:browser_version"
+  ]
+
+  def event_props(), do: @event_props
+
+  def valid_prop?(prop) when prop in @event_props, do: true
+  def valid_prop?(prop) when prop in @session_props, do: true
+  def valid_prop?("event:props:" <> prop) when byte_size(prop) > 0, do: true
+  def valid_prop?(_), do: false
 
   def props(site, query) do
     prop_filter =

lib/plausible_web/controllers/api/external_stats_controller.ex

@@ -85,7 +85,12 @@ defmodule PlausibleWeb.Api.ExternalStatsController do
   end
 
   defp validate_property(%{"property" => property}) do
-    {:ok, property}
+    if Plausible.Stats.Props.valid_prop?(property) do
+      {:ok, property}
+    else
+      {:error,
+       "Invalid property '#{property}'. Please provide a valid property for the breakdown endpoint: https://plausible.io/docs/stats-api#properties"}
+    end
   end
 
   defp validate_property(_) do

test/plausible_web/controllers/api/external_stats_controller/breakdown_test.exs

@@ -18,6 +18,32 @@ defmodule PlausibleWeb.Api.ExternalStatsController.BreakdownTest do
              }
     end
 
+    test "validates that property is valid", %{conn: conn, site: site} do
+      conn =
+        get(conn, "/api/v1/stats/breakdown", %{
+          "site_id" => site.domain,
+          "property" => "badproperty"
+        })
+
+      assert json_response(conn, 400) == %{
+               "error" =>
+                 "Invalid property 'badproperty'. Please provide a valid property for the breakdown endpoint: https://plausible.io/docs/stats-api#properties"
+             }
+    end
+
+    test "empty custom prop is invalid", %{conn: conn, site: site} do
+      conn =
+        get(conn, "/api/v1/stats/breakdown", %{
+          "site_id" => site.domain,
+          "property" => "event:props:"
+        })
+
+      assert json_response(conn, 400) == %{
+               "error" =>
+                 "Invalid property 'event:props:'. Please provide a valid property for the breakdown endpoint: https://plausible.io/docs/stats-api#properties"
+             }
+    end
+
     test "validates that correct period is used", %{conn: conn, site: site} do
       conn =
         get(conn, "/api/v1/stats/breakdown", %{