Skip to content

Open source, privacy-first web analytics. Lightweight, cookie-free Google Analytics alternative. Self-hosted or cloud.

8.3 KB
Raw Blame
defmodule Plausible.OAuth.CIMD do
  @moduledoc """
  This module fetches and validates [Client ID Metadata Documents](https://datatracker.ietf.org/doc/draft-ietf-oauth-client-id-metadata-document/).
  """

  @fetch_timeout 5_000
  @max_metadata_bytes 1_000_000
  @max_client_name_length 255
  @max_client_id_length 2048
  @max_redirect_uri_length 2048
  @reserved_response_params ~w(code state error error_description iss)

  @doc """
  Fetches the document at `client_id` and validates it.

  The `client_id` is validated first, so an invalid one costs no DNS lookup.
  """
  @spec fetch(String.t()) :: {:ok, map()} | {:error, atom() | Exception.t()}
  def fetch(client_id) do
    with :ok <- validate_client_id(client_id),
         {:ok, body} <- ssrf_get(client_id),
         {:ok, doc} <- decode_metadata(body),
         :ok <- validate_document(doc, client_id) do
      {:ok, doc}
    end
  end

  @doc """
  Validates a `client_id`.
  Must
  - use `https` scheme
  - have path component (`/` counts as a path component)
  - not have userinfo, e.g. `https://[email protected]`
  - not have fragment, e.g. `https://example.com/doc#foobar`
  - not have dot segments, e.g. `https://example.com/metadata/./..`
  """
  @spec validate_client_id(String.t() | term()) ::
          :ok | {:error, :client_id_not_https | :invalid_client_id | :client_id_too_long}
  def validate_client_id(url) when is_binary(url) and byte_size(url) > @max_client_id_length do
    {:error, :client_id_too_long}
  end

  def validate_client_id(url) when is_binary(url) do
    case URI.parse(url) do
      %URI{scheme: "https", host: host, userinfo: nil, fragment: nil, path: path}
      when is_binary(host) and host != "" and is_binary(path) and path != "" ->
        if dot_segments?(path), do: {:error, :invalid_client_id}, else: :ok

      %URI{scheme: "https", host: host} when is_binary(host) and host != "" ->
        {:error, :invalid_client_id}

      _ ->
        {:error, :client_id_not_https}
    end
  end

  def validate_client_id(_), do: {:error, :client_id_not_https}

  # Detects `.` and `..` path segments, including when they're encoded as `%2e` and `%2E`.
  defp dot_segments?(path) do
    path
    |> String.split("/")
    |> Enum.any?(fn segment ->
      (segment |> String.downcase() |> String.replace("%2e", ".")) in [".", ".."]
    end)
  end

  defp ssrf_get(url) do
    opts =
      [receive_timeout: @fetch_timeout, decode_body: false]
      |> Keyword.merge(Application.get_env(:plausible, __MODULE__, [])[:req_opts] || [])

    case Plausible.SSRF.get(url, opts) do
      {:ok, %Req.Response{status: 200, body: body}} when is_binary(body) ->
        if byte_size(body) > @max_metadata_bytes do
          {:error, :client_metadata_too_large}
        else
          {:ok, body}
        end

      {:ok, %Req.Response{}} ->
        {:error, :client_metadata_unavailable}

      {:error, reason} ->
        {:error, reason}
    end
  end

  defp decode_metadata(body) do
    case JSON.decode(body) do
      {:ok, doc} when is_map(doc) -> {:ok, doc}
      _ -> {:error, :invalid_client_metadata}
    end
  end

  @spec validate_document(map(), String.t()) ::
          :ok
          | {:error,
             :client_id_mismatch
             | :missing_redirect_uris
             | :invalid_redirect_uris
             | :invalid_client_name}
  def validate_document(doc, client_id) do
    with :ok <- validate_self_reference(doc, client_id),
         :ok <- validate_redirect_uris(doc["redirect_uris"]) do
      validate_client_name(doc["client_name"])
    end
  end

  @doc """
  Checks that the document's own `client_id` is the URL it was fetched from.
  """
  @spec validate_self_reference(map(), String.t()) :: :ok | {:error, :client_id_mismatch}
  def validate_self_reference(doc, client_id) do
    if doc["client_id"] == client_id, do: :ok, else: {:error, :client_id_mismatch}
  end

  @doc """
  Validates a metadata document's `redirect_uris` entry.

  Accepts redirect URIs with format
  - `https://` URL
  - `http://` URL on a loopback host
  - custom scheme when it contains a dot (e.g. `io.plausible://...`)

  The URI must
  - use one of the supported schemes
  - not have a fragment
  - not include userinfo
  - not contain a reserved authorization response parameter in its query

  All redirect_uris entries must be valid.
  """
  @spec validate_redirect_uris(term()) ::
          :ok | {:error, :missing_redirect_uris | :invalid_redirect_uris}
  def validate_redirect_uris(redirect_uris) when is_list(redirect_uris) and redirect_uris != [] do
    if Enum.all?(redirect_uris, &valid_redirect_uri?/1) do
      :ok
    else
      {:error, :invalid_redirect_uris}
    end
  end

  def validate_redirect_uris(_redirect_uris), do: {:error, :missing_redirect_uris}

  defp valid_redirect_uri?(uri)
       when is_binary(uri) and byte_size(uri) <= @max_redirect_uri_length do
    case URI.parse(uri) do
      %URI{fragment: fragment} when not is_nil(fragment) -> false
      %URI{userinfo: userinfo} when not is_nil(userinfo) -> false
      %URI{query: query} = parsed -> not contains_reserved_param?(query) and valid_origin?(parsed)
    end
  end

  defp valid_redirect_uri?(_uri), do: false

  defp valid_origin?(%URI{scheme: "https", host: host}), do: is_binary(host) and host != ""
  defp valid_origin?(%URI{scheme: "http", host: host}), do: loopback_host?(host)
  defp valid_origin?(_uri), do: false

  defp contains_reserved_param?(nil), do: false

  defp contains_reserved_param?(query) do
    Enum.any?(URI.query_decoder(query), fn {name, _value} -> name in @reserved_response_params end)
  rescue
    ArgumentError -> true
  end

  @doc """
  Validates a metadata document's `client_name` entry.
  """
  @spec validate_client_name(term()) :: :ok | {:error, :invalid_client_name}
  def validate_client_name(nil), do: :ok

  def validate_client_name(name) when is_binary(name) do
    if String.trim(name) != "" and String.length(name) <= @max_client_name_length and
         not unreadable?(name) do
      :ok
    else
      {:error, :invalid_client_name}
    end
  end

  def validate_client_name(_name), do: {:error, :invalid_client_name}

  # Control characters (C0, DEL, C1) truncate or garble the name when its displayed.
  # Bidi overrides `U+202A`-`U+202E` and isolates `U+2066`-`U+2069`
  # reorder the glyphs around them. Therefore, names containing such characters are unreadable and forbidden.
  defp unreadable?(name) do
    name
    |> String.to_charlist()
    |> Enum.any?(fn codepoint ->
      codepoint <= 0x1F or codepoint in 0x7F..0x9F or
        codepoint in 0x202A..0x202E or codepoint in 0x2066..0x2069
    end)
  end

  @doc """
  Checks whether a requested `redirect_uri` is registered in a CIMD document's
  `redirect_uris`.

  Non-loopback URIs must match exactly. For loopback URIs (`localhost`,
  `127.0.0.1`, `[::1]`) the port - and only the port - may differ, per
  [registration requirements](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1#name-registration-requirements)
  and [RFC 8252 §7.3](https://www.rfc-editor.org/rfc/rfc8252.html#section-7.3),
  because a native client binds a random port it cannot know in advance.

  Every other component must match exactly, so adding a query string to a
  registered loopback URI does not match it. Scheme and host are compared
  case-insensitively (RFC 3986 sections 3.1 and 3.2.2), nothing else is.
  """
  @spec redirect_uri_registered?(String.t() | nil, [String.t()]) :: boolean()
  def redirect_uri_registered?(redirect_uri, registered) when is_binary(redirect_uri) do
    redirect_uri in registered or loopback_match?(redirect_uri, registered)
  end

  def redirect_uri_registered?(_redirect_uri, _registered), do: false

  defp loopback_match?(redirect_uri, registered) do
    uri = URI.parse(redirect_uri)

    loopback_host?(uri.host) and
      Enum.any?(registered, fn candidate ->
        registered_uri = URI.parse(candidate)

        loopback_host?(registered_uri.host) and equal_but_for_port?(registered_uri, uri)
      end)
  end

  defp loopback_host?(host), do: downcase(host) in ["localhost", "127.0.0.1", "::1"]

  defp equal_but_for_port?(%URI{} = a, %URI{} = b) do
    downcase(a.scheme) == downcase(b.scheme) and
      is_nil(a.userinfo) and
      is_nil(b.userinfo) and
      downcase(a.host) == downcase(b.host) and
      a.path == b.path and
      a.query == b.query and
      a.fragment == b.fragment
  end

  defp downcase(nil), do: nil
  defp downcase(value), do: String.downcase(value)
end