Merge branch 'main' into hb-refactor-readme

Author: hugobarauna

README.md

@@ -198,12 +198,16 @@ The following options are available:
 
   * `:allow_remote_access` - Tidewave only allows requests from localhost by default, even if your server listens on other interfaces, for security purposes. Read [our security guidelines for more information and when to allow remote access](https://hexdocs.pm/tidewave/security.html) (if you know what you are doing)
 
+  * `:allowed_origins` - a list of values matched against the `Origin` header to prevent cross origin and DNS rebinding attacks. Each value must be a string of shape `[scheme:]//host[:port]`, where both scheme and port are optional. The host may also start with "*". Example: `["//localhost:8000", "//*.test"]`
+
   * `:inspect_opts` - custom options passed to `Kernel.inspect/2` when formatting some tool results. Defaults to: `[charlists: :as_lists, limit: 50, pretty: true]`
 
   * `:team` - set your Tidewave Team configuration, such as `team: [id: "my-company"]`
 
   * `:toolbar` - controls whether the Tidewave toolbar is injected into your HTML pages. Defaults to `true`
 
+  * `tmp_dir` - temporary directory Tidewave uses for screenshots and recordings. It must be a relative directory to the current application root. Defaults to `tmp`, storing files under `tmp/tidewave/screenshots` and `tmp/tidewave/recordings`
+
 ## License
 
 Copyright (c) 2025 Dashbit

lib/tidewave.ex

@@ -36,7 +36,8 @@ defmodule Tidewave do
       team: Keyword.get(opts, :team, []),
       toolbar: Keyword.get(opts, :toolbar, true),
       inspect_opts:
-        Keyword.get(opts, :inspect_opts, charlists: :as_lists, limit: 50, pretty: true)
+        Keyword.get(opts, :inspect_opts, charlists: :as_lists, limit: 50, pretty: true),
+      tmp_dir: Keyword.get(opts, :tmp_dir, "tmp")
     }
   end
 
@@ -184,7 +185,8 @@ defmodule Tidewave do
       framework_type: "phoenix",
       tidewave_version: package_version(:tidewave),
       team: Map.new(plug_config.team),
-      local_port: Plug.Conn.get_sock_data(conn).port
+      local_port: Plug.Conn.get_sock_data(conn).port,
+      tmp_dir: plug_config.tmp_dir
     }
   end
 

lib/tidewave/router.ex

@@ -113,73 +113,106 @@ defmodule Tidewave.Router do
 
   defp check_origin(conn, _opts) do
     case {conn.path_info, get_req_header(conn, "origin")} do
+      # No origin header is always allowed
+      {_, []} ->
+        conn
+
       # GET / allows any origin
       {[], _} ->
         conn
 
       # /config contains metadata for discovery and it is safe to allow any origin
-      {["config"], _} ->
+      {[no_check_origin], _} when no_check_origin in ["config"] ->
         conn
 
-      # The control page WebSocket is the one endpoint that legitimately
-      # receives an Origin header (browsers always send it on WebSocket
-      # upgrades), so it gets a same-origin check instead.
-      {["ws"], origin} ->
-        require_same_origin(conn, origin)
-
-      # No origin header is always allowed
-      {_, []} ->
-        conn
+      # /ws and /upload are acessed from the web app and must have origins
+      {[check_origin], [origin]} when check_origin in ["ws", "upload"] ->
+        if valid_allowed_origin?(conn, URI.parse(origin)) do
+          conn
+        else
+          log_and_send_403(conn, """
+          For security reasons, Tidewave only accepts requests from the same origin your web app is running on.
 
-      # Uploads are allowed from the same origin.
-      {["upload"], origin} ->
-        require_same_origin(conn, origin)
+          If you really want to allow remote connections, configure the Tidewave with the `allowed_origins: [#{inspect(origin)}]` option.
+          """)
+        end
 
-      # /mcp refuses if origin header is set
+      # /mcp and everything else fails if origin header is set
       {_, _} ->
         log_and_send_403(conn, """
         For security reasons, Tidewave does not accept requests with an origin header for this endpoint.
         """)
     end
   end
 
-  defp require_same_origin(conn, [origin | _]) do
-    if origin_host(origin) in allowed_origin_hosts(conn.private.tidewave_config) do
-      conn
-    else
-      log_and_send_403(conn, """
-      For security reasons, this page only allows connections from the application's own origin.
-      """)
-    end
+  defp valid_allowed_origin?(conn, origin) do
+    allowed_origins =
+      case conn.private.tidewave_config.allowed_origins do
+        [_ | _] = allowed_origins -> allowed_origins
+        _ -> [host_from_endpoint!(conn)]
+      end
+
+    Enum.any?(allowed_origins, &allowed_origin?(origin, parse_allowed_origin!(&1)))
   end
 
-  defp origin_host(origin) do
-    URI.parse(origin).host
+  defp host_from_endpoint!(conn) do
+    case conn.private do
+      %{tidewave_config: %{phoenix_endpoint: endpoint}} when not is_nil(endpoint) ->
+        "//#{host_from_endpoint(endpoint)}"
+
+      _ ->
+        raise """
+        no Phoenix endpoint found! You must manually configure the \
+        allowed origins for Tidewave by setting the `:allowed_origins` \
+        option on the Tidewave plug:
+
+            plug Tidewave, allowed_origins: ["//localhost"]
+        """
+    end
   end
 
-  defp allowed_origin_hosts(%{allowed_origins: [_ | _] = allowed_origins}) do
-    Enum.map(allowed_origins, &origin_or_host_to_host/1)
+  defp host_from_endpoint(endpoint) do
+    cond do
+      function_exported?(endpoint, :struct_url, 0) ->
+        endpoint.struct_url().host
+
+      function_exported?(endpoint, :config, 1) ->
+        endpoint.config(:url)[:host]
+
+      true ->
+        nil
+    end || raise_missing_allowed_origins!()
   end
 
-  defp allowed_origin_hosts(%{phoenix_endpoint: endpoint}) when not is_nil(endpoint) do
-    if host = endpoint.config(:url)[:host] do
-      [host]
-    else
-      raise_missing_allowed_origins!()
+  defp parse_allowed_origin!(origin) do
+    case URI.parse(origin) do
+      %URI{host: nil} ->
+        raise ArgumentError,
+              "invalid :allowed_origins value: #{inspect(origin)}. " <>
+                "Expected an origin with a host that is parsable by URI.parse/1. For example: " <>
+                "[\"https://example.com\", \"//another.com:888\", \"//other.com\"]"
+
+      %URI{} = uri ->
+        uri
     end
   end
 
-  defp allowed_origin_hosts(_config) do
-    raise_missing_allowed_origins!()
+  defp allowed_origin?(origin, allowed) do
+    compare?(origin.scheme, allowed.scheme) and
+      compare?(origin.port, allowed.port) and
+      compare_host?(origin.host, allowed.host)
   end
 
-  defp origin_or_host_to_host(origin_or_host) do
-    case URI.parse(origin_or_host) do
-      %URI{host: host} when is_binary(host) -> host
-      _ -> origin_or_host
-    end
+  defp compare?(request_val, allowed_val) do
+    is_nil(allowed_val) or request_val == allowed_val
   end
 
+  defp compare_host?(request_host, "*." <> allowed_host),
+    do: request_host == allowed_host or String.ends_with?(request_host, "." <> allowed_host)
+
+  defp compare_host?(request_host, allowed_host),
+    do: request_host == allowed_host
+
   defp raise_missing_allowed_origins! do
     raise """
     Tidewave cannot verify the origin because no allowed origins are configured and no Phoenix endpoint URL host is available.
@@ -226,8 +259,9 @@ defmodule Tidewave.Router do
     with %{"type" => type, "file" => %Plug.Upload{} = upload}
          when type in @allowed_upload_types <- conn.body_params,
          true <- is_allowed_content_type?(upload) do
-      create_upload_dir!(type)
-      dest = upload_path(type, upload.filename)
+      tmp_dir = conn.private.tidewave_config.tmp_dir
+      create_upload_dir!(tmp_dir, type)
+      dest = upload_path(tmp_dir, type, upload.filename)
       File.cp!(upload.path, dest)
 
       conn
@@ -243,21 +277,17 @@ defmodule Tidewave.Router do
     end
   end
 
-  defp create_upload_dir!(type) do
-    File.mkdir_p!(upload_dir(type))
-  end
-
-  defp tmp_dir do
-    Application.get_env(:tidewave, :tmp_dir, "tmp")
+  defp create_upload_dir!(tmp_dir, type) do
+    File.mkdir_p!(upload_dir(tmp_dir, type))
   end
 
-  defp upload_dir(type) do
-    tmp_dir()
+  defp upload_dir(tmp_dir, type) do
+    tmp_dir
     |> Path.join("tidewave")
     |> Path.join(folder_for_type(type))
   end
 
-  defp upload_path(type, filename) do
+  defp upload_path(tmp_dir, type, filename) do
     ext = filename |> Path.extname() |> String.downcase()
 
     cond do
@@ -268,7 +298,7 @@ defmodule Tidewave.Router do
         raise "filename must have a valid extension (.png, .jpg, .jpeg, .webm): #{filename}"
 
       true ->
-        Path.join(upload_dir(type), filename)
+        Path.join(upload_dir(tmp_dir, type), filename)
     end
   end
 

test/control_test.exs

@@ -37,7 +37,7 @@ defmodule Tidewave.ControlPlaneTest do
       conn =
         ws_conn()
         |> Plug.Conn.put_req_header("origin", "http://control.example.com")
-        |> Tidewave.call(Tidewave.init(allowed_origins: ["control.example.com"]))
+        |> Tidewave.call(Tidewave.init(allowed_origins: ["//control.example.com"]))
 
       assert conn.status == nil
     end
@@ -51,11 +51,20 @@ defmodule Tidewave.ControlPlaneTest do
       assert conn.status == nil
     end
 
-    test "allows a websocket upgrade from the same host as an allowed full origin" do
+    test "allows a websocket upgrade from the same host as an allowed port-less origin" do
       conn =
         ws_conn()
         |> Plug.Conn.put_req_header("origin", "http://control.example.com:5173")
-        |> Tidewave.call(Tidewave.init(allowed_origins: ["http://control.example.com:4000"]))
+        |> Tidewave.call(Tidewave.init(allowed_origins: ["//control.example.com"]))
+
+      assert conn.status == nil
+    end
+
+    test "allows a websocket upgrade from a wildcard origin" do
+      conn =
+        ws_conn()
+        |> Plug.Conn.put_req_header("origin", "http://control.example.com")
+        |> Tidewave.call(Tidewave.init(allowed_origins: ["//*.example.com"]))
 
       assert conn.status == nil
     end
@@ -97,6 +106,16 @@ defmodule Tidewave.ControlPlaneTest do
         |> Tidewave.call(Tidewave.init([]))
       end
     end
+
+    test "raises on invalid allowed origin configuration" do
+      assert_raise ArgumentError,
+                   ~r/invalid :allowed_origins value.*Expected an origin with a host/,
+                   fn ->
+                     ws_conn()
+                     |> Plug.Conn.put_req_header("origin", "http://app.example.com")
+                     |> Tidewave.call(Tidewave.init(allowed_origins: ["invalid-origin"]))
+                   end
+    end
   end
 
   defp get_resp_header_value(conn, key) do

test/tidewave_test.exs

@@ -159,6 +159,7 @@ defmodule TidewaveTest do
                "framework_type" => "phoenix",
                "project_name" => "tidewave",
                "team" => %{},
+               "tmp_dir" => "tmp",
                "tidewave_version" => _
              } = Jason.decode!(conn.resp_body)
     end