Skip to content

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

Implement Plugins API Token schema (#3370)

hq1311d66b341bc
diff --git a/lib/plausible/plugins/api/token.ex b/lib/plausible/plugins/api/token.ex
new file mode 100644
index 0000000000..aac7f14e09
--- /dev/null
+++ b/lib/plausible/plugins/api/token.ex
@@ -0,0 +1,79 @@
+defmodule Plausible.Plugins.API.Token do
+ @moduledoc """
+ Ecto schema for Plugins API Tokens.
+ Tokens are stored hashed and require a description.
+
+ Tokens are considered secret, although the Plugins API
+ by nature will expose very little, if any, destructive/insecure operations.
+
+ The raw token version is meant to be presented to the user upon creation.
+ It is prefixed with a plain text identifier allowing source scanning
+ for leaked secrets.
+ """
+ use Ecto.Schema
+ import Ecto.Changeset
+
+ alias Plausible.Site
+
+ @type t() :: %__MODULE__{}
+
+ @primary_key {:id, :binary_id, autogenerate: true}
+ schema "plugins_api_tokens" do
+ timestamps()
+ field(:token_hash, :binary)
+ field(:description, :string)
+ field(:hint, :string)
+
+ belongs_to(:site, Site)
+ end
+
+ @spec generate(String.t()) :: map()
+ def generate(random_bytes \\ random_bytes()) do
+ raw = prefixed(random_bytes)
+ hash = hash(raw)
+
+ %{
+ raw: raw,
+ hash: hash
+ }
+ end
+
+ @spec hash(String.t()) :: binary()
+ def hash(raw) do
+ :crypto.hash(:sha256, raw)
+ end
+
+ @fields [:description, :site_id]
+ @required_fields [:description, :site, :token_hash, :hint]
+
+ @spec insert_changeset(Site.t(), map(), map()) :: Ecto.Changeset.t()
+ def insert_changeset(site, %{hash: hash, raw: raw}, attrs \\ %{}) do
+ %__MODULE__{}
+ |> cast(attrs, @fields)
+ |> put_change(:token_hash, hash)
+ |> put_change(:hint, String.slice(raw, -4, 4))
+ |> put_assoc(:site, site)
+ |> validate_required(@required_fields)
+ end
+
+ @doc """
+ Raw tokens are prefixed so that tools like
+ https://docs.github.com/en/code-security/secret-scanning/about-secret-scanning
+ can scan repositories for accidental secret commits.
+ """
+ def prefix() do
+ case {Plausible.Release.selfhost?(), Application.get_env(:plausible, :environment)} do
+ {true, _} -> "plausible-plugin-selfhost"
+ {false, "prod"} -> "plausible-plugin"
+ {false, env} -> "plausible-plugin-#{env}"
+ end
+ end
+
+ defp prefixed(random_bytes) do
+ Enum.join([prefix(), random_bytes], "-")
+ end
+
+ defp random_bytes() do
+ 30 |> :crypto.strong_rand_bytes() |> Base.encode64()
+ end
+end
diff --git a/lib/plausible/plugins/api/tokens.ex b/lib/plausible/plugins/api/tokens.ex
new file mode 100644
index 0000000000..70d0be156f
--- /dev/null
+++ b/lib/plausible/plugins/api/tokens.ex
@@ -0,0 +1,40 @@
+defmodule Plausible.Plugins.API.Tokens do
+ @moduledoc """
+ Context module for Plugins API Tokens.
+ Exposes high-level operation for token-based authentication flows.
+ """
+ alias Plausible.Plugins.API.Token
+ alias Plausible.Site
+ alias Plausible.Repo
+
+ import Ecto.Query
+
+ @spec create(Site.t(), String.t()) ::
+ {:ok, Token.t(), String.t()} | {:error, Ecto.Changeset.t()}
+ def create(%Site{} = site, description) do
+ with generated_token <- Token.generate(),
+ changeset <- Token.insert_changeset(site, generated_token, %{description: description}),
+ {:ok, saved_token} <- Repo.insert(changeset) do
+ {:ok, saved_token, generated_token.raw}
+ end
+ end
+
+ @spec find(String.t(), String.t()) :: {:ok, Token.t()} | {:error, :not_found}
+ def find(domain, raw) do
+ found =
+ Repo.one(
+ from(t in Token,
+ inner_join: s in Site,
+ on: s.id == t.site_id,
+ where: t.token_hash == ^Token.hash(raw),
+ where: s.domain == ^domain or s.domain_changed_from == ^domain
+ )
+ )
+
+ if found do
+ {:ok, found}
+ else
+ {:error, :not_found}
+ end
+ end
+end
diff --git a/priv/repo/migrations/20230925072840_plugins_api_tokens.exs b/priv/repo/migrations/20230925072840_plugins_api_tokens.exs
new file mode 100644
index 0000000000..6a7f7b42cd
--- /dev/null
+++ b/priv/repo/migrations/20230925072840_plugins_api_tokens.exs
@@ -0,0 +1,16 @@
+defmodule Plausible.Repo.Migrations.PluginsAPITokens do
+ use Ecto.Migration
+
+ def change do
+ create table("plugins_api_tokens", primary_key: false) do
+ add(:id, :uuid, primary_key: true)
+ add(:site_id, references(:sites, on_delete: :delete_all), null: false)
+ add(:token_hash, :bytea, null: false)
+ add(:hint, :string, null: false)
+ add(:description, :string, null: false)
+ timestamps()
+ end
+
+ create(index(:plugins_api_tokens, [:site_id, :token_hash]))
+ end
+end
diff --git a/test/plausible/plugins/api/token_test.exs b/test/plausible/plugins/api/token_test.exs
new file mode 100644
index 0000000000..94b2887b0c
--- /dev/null
+++ b/test/plausible/plugins/api/token_test.exs
@@ -0,0 +1,73 @@
+defmodule Plausible.Plugins.API.TokenTest do
+ use Plausible.DataCase, async: false
+
+ alias Plausible.Plugins.API.Token
+
+ test "basic token properties" do
+ t1 = Token.generate()
+ t2 = Token.generate()
+
+ assert is_binary(t1.raw)
+ assert is_binary(t1.hash)
+
+ assert is_binary(t2.raw)
+ assert is_binary(t2.hash)
+
+ assert byte_size(t1.hash) == 32
+ assert byte_size(t2.hash) == 32
+
+ assert <<"plausible-plugin-test-", _::binary-size(40)>> = t1.raw
+ assert <<"plausible-plugin-test-", _::binary-size(40)>> = t2.raw
+
+ assert t1.raw != t2.raw
+ assert t1.hash != t2.hash
+ end
+
+ describe "prefix/0" do
+ test "default prefix" do
+ assert Token.prefix() == "plausible-plugin-test"
+ end
+
+ test "selfhosted prefix" do
+ patch_env(:is_selfhost, true)
+ assert Token.prefix() == "plausible-plugin-selfhost"
+ end
+
+ test "prod prefix" do
+ patch_env(:environment, "prod")
+ assert Token.prefix() == "plausible-plugin"
+ end
+
+ test "staging prefix" do
+ patch_env(:environment, "staging")
+ assert Token.prefix() == "plausible-plugin-staging"
+ end
+ end
+
+ describe "insert_changeset/2" do
+ test "required fields" do
+ changeset = Token.insert_changeset(nil, %{raw: "", hash: ""}, %{})
+ refute changeset.valid?
+
+ assert [
+ description: {"can't be blank", _},
+ site: {"can't be blank", _},
+ token_hash: {"can't be blank", _},
+ hint: {"can't be blank", _}
+ ] = changeset.errors
+ end
+
+ test "valid changeset" do
+ site = build(:site, id: 1_892_787)
+
+ changeset =
+ Token.insert_changeset(site, Token.generate(), %{
+ "description" => "My token"
+ })
+
+ assert changeset.valid?
+
+ assert Ecto.Changeset.get_field(changeset, :site).id == 1_892_787
+ end
+ end
+end
diff --git a/test/plausible/plugins/api/tokens_test.exs b/test/plausible/plugins/api/tokens_test.exs
new file mode 100644
index 0000000000..fedaa3e282
--- /dev/null
+++ b/test/plausible/plugins/api/tokens_test.exs
@@ -0,0 +1,56 @@
+defmodule Plausible.Plugins.API.TokensTest do
+ use Plausible.DataCase, async: true
+
+ alias Plausible.Plugins.API.Token
+ alias Plausible.Plugins.API.Tokens
+ alias Plausible.Repo
+
+ describe "create/2" do
+ test "generates and stores the token" do
+ site = insert(:site)
+ assert {:ok, %Token{} = token, raw} = Tokens.create(site, "My test token")
+ assert <<"plausible-plugin-test-", _::binary-size(40)>> = raw
+
+ from_db = Repo.get(Token, token.id)
+
+ assert from_db.token_hash == token.token_hash
+ assert from_db.description == "My test token"
+ assert from_db.site_id == site.id
+ hint = from_db.hint
+ assert is_binary(hint) and byte_size(hint) == 4
+ assert String.ends_with?(raw, hint)
+ end
+
+ test "fails to store on input errors" do
+ site = insert(:site)
+ assert {:error, %Ecto.Changeset{}} = Tokens.create(site, nil)
+ end
+ end
+
+ describe "find/2" do
+ test "finds the right token" do
+ site = insert(:site)
+ assert {:ok, _, raw} = Tokens.create(site, "My test token")
+ assert {:ok, found} = Tokens.find(site.domain, raw)
+ assert found.id == found.id
+ end
+
+ test "finds the right token after domain change" do
+ site = insert(:site, domain: "foo1.example.com")
+ assert {:ok, _, raw} = Tokens.create(site, "My test token")
+
+ {:ok, _} = Plausible.Site.Domain.change(site, "foo2.example.com")
+
+ assert {:ok, found} = Tokens.find("foo1.example.com", raw)
+ assert {:ok, ^found} = Tokens.find("foo2.example.com", raw)
+ end
+
+ test "fails to find the token" do
+ site = insert(:site)
+ assert {:ok, _, _} = Tokens.create(site, "My test token")
+
+ assert {:error, :not_found} = Tokens.find(site.domain, "non-existing")
+ assert {:error, :not_found} = Tokens.find("non-existing", "non-existing")
+ end
+ end
+end