diff --git a/AGENTS.md b/AGENTS.md
index 8de84a2..f9a1995 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -66,3 +66,65 @@ The five canonical triage roles, each label string equal to its name (`needs-tri
### Domain docs
Single-context: `GLOSSARY.md` and `docs/adr/` at the repo root. See `docs/agents/domain.md`.
+
+
+
+## Authentication
+
+- **Always** handle authentication flow at the router level with proper redirects
+- **Always** be mindful of where to place routes. `phx.gen.auth` creates multiple router plugs and `live_session` scopes:
+ - A plug `:fetch_current_scope_for_user` that is included in the default browser pipeline
+ - A plug `:require_authenticated_user` that redirects to the log in page when the user is not authenticated
+ - A `live_session :current_user` scope - for routes that need the current user but don't require authentication, similar to `:fetch_current_scope_for_user`
+ - A `live_session :require_authenticated_user` scope - for routes that require authentication, similar to the plug with the same name
+ - In both cases, a `@current_scope` is assigned to the Plug connection and LiveView socket
+ - A plug `redirect_if_user_is_authenticated` that redirects to a default path in case the user is authenticated - useful for a registration page that should only be shown to unauthenticated users
+- **Always let the user know in which router scopes, `live_session`, and pipeline you are placing the route, AND SAY WHY**
+- `phx.gen.auth` assigns the `current_scope` assign - it **does not assign a `current_user` assign**
+- Always pass the assign `current_scope` to context modules as first argument. When performing queries, use `current_scope.user` to filter the query results
+- To derive/access `current_user` in templates, **always use the `@current_scope.user`**, never use **`@current_user`** in templates or LiveViews
+- **Never** duplicate `live_session` names. A `live_session :current_user` can only be defined __once__ in the router, so all routes for the `live_session :current_user` must be grouped in a single block
+- Anytime you hit `current_scope` errors or the logged in session isn't displaying the right content, **always double check the router and ensure you are using the correct plug and `live_session` as described below**
+
+### Routes that require authentication
+
+LiveViews that require login should **always be placed inside the __existing__ `live_session :require_authenticated_user` block**:
+
+ scope "/", AppWeb do
+ pipe_through [:browser, :require_authenticated_user]
+
+ live_session :require_authenticated_user,
+ on_mount: [{ChesstrainerWeb.UserAuth, :require_authenticated}] do
+ # phx.gen.auth generated routes
+ live "/users/settings", UserLive.Settings, :edit
+ live "/users/settings/confirm-email/:token", UserLive.Settings, :confirm_email
+ # our own routes that require logged in user
+ live "/", MyLiveThatRequiresAuth, :index
+ end
+ end
+
+Controller routes must be placed in a scope that sets the `:require_authenticated_user` plug:
+
+ scope "/", AppWeb do
+ pipe_through [:browser, :require_authenticated_user]
+
+ get "/", MyControllerThatRequiresAuth, :index
+ end
+
+### Routes that work with or without authentication
+
+LiveViews that can work with or without authentication, **always use the __existing__ `:current_user` scope**, ie:
+
+ scope "/", MyAppWeb do
+ pipe_through [:browser]
+
+ live_session :current_user,
+ on_mount: [{ChesstrainerWeb.UserAuth, :mount_current_scope}] do
+ # our own routes that work with or without authentication
+ live "/", PublicLive
+ end
+ end
+
+Controllers automatically have the `current_scope` available if they use the `:browser` pipeline.
+
+
\ No newline at end of file
diff --git a/GLOSSARY.md b/GLOSSARY.md
index 2f740a1..de09c0b 100644
--- a/GLOSSARY.md
+++ b/GLOSSARY.md
@@ -30,6 +30,20 @@ pieces each side has, written strongest side first and colour-agnostic
(e.g. "KQ v KR"). Used to group and search endgames by material.
_Avoid_: Material signature, hash
+## Identity & access
+
+**User**:
+A person who can sign in to the trainer, identified by a unique email address and a unique username.
+_Avoid_: Account, player
+
+**Role**:
+A user's authority tier — `member`, `moderator`, `admin` or `super_admin` — deciding access to the admin area and the power to manage other users.
+_Avoid_: Permission, access level
+
+**Plan**:
+A user's subscription tier — `free` or `premium` — independent of their role.
+_Avoid_: Tier, subscription, membership
+
## Play
**Winning side**:
diff --git a/config/config.exs b/config/config.exs
index c348dbe..a4f5365 100644
--- a/config/config.exs
+++ b/config/config.exs
@@ -7,6 +7,19 @@
# General application configuration
import Config
+config :chesstrainer, :scopes,
+ user: [
+ default: true,
+ module: Chesstrainer.Accounts.Scope,
+ assign_key: :current_scope,
+ access_path: [:user, :id],
+ schema_key: :user_id,
+ schema_type: :binary_id,
+ schema_table: :users,
+ test_data_fixture: Chesstrainer.AccountsFixtures,
+ test_setup_helper: :register_and_log_in_user
+ ]
+
config :chesstrainer,
ecto_repos: [Chesstrainer.Repo],
generators: [timestamp_type: :utc_datetime]
diff --git a/config/test.exs b/config/test.exs
index c0bc9b7..bf74e94 100644
--- a/config/test.exs
+++ b/config/test.exs
@@ -1,5 +1,8 @@
import Config
+# Only in tests, remove the complexity from the password hashing algorithm
+config :bcrypt_elixir, :log_rounds, 1
+
# Point the local Fathom backend at the committed 3-piece fixtures.
config :chesstrainer, :tablebase_path, Path.expand("../test/fixtures/tablebase", __DIR__)
diff --git a/lib/chesstrainer/accounts.ex b/lib/chesstrainer/accounts.ex
new file mode 100644
index 0000000..0438cf3
--- /dev/null
+++ b/lib/chesstrainer/accounts.ex
@@ -0,0 +1,274 @@
+defmodule Chesstrainer.Accounts do
+ @moduledoc """
+ The Accounts context.
+ """
+
+ import Ecto.Query, warn: false
+ alias Chesstrainer.Repo
+
+ alias Chesstrainer.Accounts.{User, UserToken, UserNotifier}
+
+ ## Database getters
+
+ @doc """
+ Gets a user by email.
+
+ ## Examples
+
+ iex> get_user_by_email("foo@example.com")
+ %User{}
+
+ iex> get_user_by_email("unknown@example.com")
+ nil
+
+ """
+ def get_user_by_email(email) when is_binary(email) do
+ Repo.get_by(User, email: email)
+ end
+
+ @doc """
+ Gets a user by email or username.
+
+ Email and username are both `citext`, so the lookup ignores case.
+
+ ## Examples
+
+ iex> get_user_by_login("foo@example.com")
+ %User{}
+
+ iex> get_user_by_login("unknown")
+ nil
+
+ """
+ def get_user_by_login(login) when is_binary(login) do
+ login = String.trim(login)
+
+ from(u in User, where: u.email == ^login or u.username == ^login, limit: 1)
+ |> Repo.one()
+ end
+
+ @doc """
+ Gets a user by email or username and password.
+
+ ## Examples
+
+ iex> get_user_by_login_and_password("foo@example.com", "correct_password")
+ %User{}
+
+ iex> get_user_by_login_and_password("foo@example.com", "invalid_password")
+ nil
+
+ """
+ def get_user_by_login_and_password(login, password)
+ when is_binary(login) and is_binary(password) do
+ user = get_user_by_login(login)
+ if User.valid_password?(user, password), do: user
+ end
+
+ @doc """
+ Gets a single user.
+
+ Raises `Ecto.NoResultsError` if the User does not exist.
+
+ ## Examples
+
+ iex> get_user!(123)
+ %User{}
+
+ iex> get_user!(456)
+ ** (Ecto.NoResultsError)
+
+ """
+ def get_user!(id), do: Repo.get!(User, id)
+
+ ## User registration
+
+ @doc """
+ Registers a user.
+
+ ## Examples
+
+ iex> register_user(%{field: value})
+ {:ok, %User{}}
+
+ iex> register_user(%{field: bad_value})
+ {:error, %Ecto.Changeset{}}
+
+ """
+ def register_user(attrs) do
+ %User{}
+ |> User.registration_changeset(attrs)
+ # Accounts are usable straight away; email confirmation is intentionally off
+ # because no production mailer adapter is configured yet.
+ |> Ecto.Changeset.put_change(:confirmed_at, DateTime.utc_now(:second))
+ |> Repo.insert()
+ end
+
+ @doc """
+ Returns an `%Ecto.Changeset{}` for tracking user registration changes.
+
+ See `Chesstrainer.Accounts.User.registration_changeset/3`.
+ """
+ def change_user_registration(user, attrs \\ %{}, opts \\ []) do
+ User.registration_changeset(user, attrs, opts)
+ end
+
+ @doc """
+ Updates a user's authority role.
+
+ This is the only supported path for changing roles; registration never casts
+ `role`, so a user cannot promote themselves.
+ """
+ def update_user_role(%User{} = user, role) do
+ user
+ |> User.role_changeset(%{role: role})
+ |> Repo.update()
+ end
+
+ ## Settings
+
+ @doc """
+ Checks whether the user is in sudo mode.
+
+ The user is in sudo mode when the last authentication was done no further
+ than 20 minutes ago. The limit can be given as second argument in minutes.
+ """
+ def sudo_mode?(user, minutes \\ -20)
+
+ def sudo_mode?(%User{authenticated_at: ts}, minutes) when is_struct(ts, DateTime) do
+ DateTime.after?(ts, DateTime.utc_now() |> DateTime.add(minutes, :minute))
+ end
+
+ def sudo_mode?(_user, _minutes), do: false
+
+ @doc """
+ Returns an `%Ecto.Changeset{}` for changing the user email.
+
+ See `Chesstrainer.Accounts.User.email_changeset/3` for a list of supported options.
+
+ ## Examples
+
+ iex> change_user_email(user)
+ %Ecto.Changeset{data: %User{}}
+
+ """
+ def change_user_email(user, attrs \\ %{}, opts \\ []) do
+ User.email_changeset(user, attrs, opts)
+ end
+
+ @doc """
+ Updates the user email using the given token.
+
+ If the token matches, the user email is updated and the token is deleted.
+ """
+ def update_user_email(user, token) do
+ context = "change:#{user.email}"
+
+ Repo.transact(fn ->
+ with {:ok, query} <- UserToken.verify_change_email_token_query(token, context),
+ %UserToken{sent_to: email} <- Repo.one(query),
+ {:ok, user} <- Repo.update(User.email_changeset(user, %{email: email})),
+ {_count, _result} <-
+ Repo.delete_all(from(UserToken, where: [user_id: ^user.id, context: ^context])) do
+ {:ok, user}
+ else
+ _ -> {:error, :transaction_aborted}
+ end
+ end)
+ end
+
+ @doc """
+ Returns an `%Ecto.Changeset{}` for changing the user password.
+
+ See `Chesstrainer.Accounts.User.password_changeset/3` for a list of supported options.
+
+ ## Examples
+
+ iex> change_user_password(user)
+ %Ecto.Changeset{data: %User{}}
+
+ """
+ def change_user_password(user, attrs \\ %{}, opts \\ []) do
+ User.password_changeset(user, attrs, opts)
+ end
+
+ @doc """
+ Updates the user password.
+
+ Returns a tuple with the updated user, as well as a list of expired tokens.
+
+ ## Examples
+
+ iex> update_user_password(user, %{password: ...})
+ {:ok, {%User{}, [...]}}
+
+ iex> update_user_password(user, %{password: "too short"})
+ {:error, %Ecto.Changeset{}}
+
+ """
+ def update_user_password(user, attrs) do
+ user
+ |> User.password_changeset(attrs)
+ |> update_user_and_delete_all_tokens()
+ end
+
+ ## Session
+
+ @doc """
+ Generates a session token.
+ """
+ def generate_user_session_token(user) do
+ {token, user_token} = UserToken.build_session_token(user)
+ Repo.insert!(user_token)
+ token
+ end
+
+ @doc """
+ Gets the user with the given signed token.
+
+ If the token is valid `{user, token_inserted_at}` is returned, otherwise `nil` is returned.
+ """
+ def get_user_by_session_token(token) do
+ {:ok, query} = UserToken.verify_session_token_query(token)
+ Repo.one(query)
+ end
+
+ @doc ~S"""
+ Delivers the update email instructions to the given user.
+
+ ## Examples
+
+ iex> deliver_user_update_email_instructions(user, current_email, &url(~p"/users/settings/confirm-email/#{&1}"))
+ {:ok, %{to: ..., body: ...}}
+
+ """
+ def deliver_user_update_email_instructions(%User{} = user, current_email, update_email_url_fun)
+ when is_function(update_email_url_fun, 1) do
+ {encoded_token, user_token} = UserToken.build_email_token(user, "change:#{current_email}")
+
+ Repo.insert!(user_token)
+ UserNotifier.deliver_update_email_instructions(user, update_email_url_fun.(encoded_token))
+ end
+
+ @doc """
+ Deletes the signed token with the given context.
+ """
+ def delete_user_session_token(token) do
+ Repo.delete_all(from(UserToken, where: [token: ^token, context: "session"]))
+ :ok
+ end
+
+ ## Token helper
+
+ defp update_user_and_delete_all_tokens(changeset) do
+ Repo.transact(fn ->
+ with {:ok, user} <- Repo.update(changeset) do
+ tokens_to_expire = Repo.all_by(UserToken, user_id: user.id)
+
+ Repo.delete_all(from(t in UserToken, where: t.id in ^Enum.map(tokens_to_expire, & &1.id)))
+
+ {:ok, {user, tokens_to_expire}}
+ end
+ end)
+ end
+end
diff --git a/lib/chesstrainer/accounts/role.ex b/lib/chesstrainer/accounts/role.ex
new file mode 100644
index 0000000..e10433b
--- /dev/null
+++ b/lib/chesstrainer/accounts/role.ex
@@ -0,0 +1,37 @@
+defmodule Chesstrainer.Accounts.Role do
+ @moduledoc """
+ The ordered authority tiers a user can hold.
+
+ A higher rank may do everything a lower rank may, so authorization checks
+ should ask for the minimum tier they need via `at_least?/2`.
+ """
+
+ @values [:member, :moderator, :admin, :super_admin]
+
+ @ranks %{
+ member: 0,
+ moderator: 1,
+ admin: 2,
+ super_admin: 3
+ }
+
+ @doc "All roles, ordered from least to most authority."
+ def values, do: @values
+
+ @doc "The numeric rank of a role."
+ def rank(role) when role in @values, do: Map.fetch!(@ranks, role)
+
+ @doc """
+ Returns true when `role` is at least as authoritative as `minimum`.
+
+ A missing role (no user) never satisfies any minimum.
+ """
+ def at_least?(role, minimum) when role in @values and minimum in @values do
+ rank(role) >= rank(minimum)
+ end
+
+ def at_least?(_role, _minimum), do: false
+
+ @doc "Returns true when the role may use the admin area."
+ def admin?(role), do: at_least?(role, :admin)
+end
diff --git a/lib/chesstrainer/accounts/scope.ex b/lib/chesstrainer/accounts/scope.ex
new file mode 100644
index 0000000..4970abe
--- /dev/null
+++ b/lib/chesstrainer/accounts/scope.ex
@@ -0,0 +1,33 @@
+defmodule Chesstrainer.Accounts.Scope do
+ @moduledoc """
+ Defines the scope of the caller to be used throughout the app.
+
+ The `Chesstrainer.Accounts.Scope` allows public interfaces to receive
+ information about the caller, such as if the call is initiated from an
+ end-user, and if so, which user. Additionally, such a scope can carry fields
+ such as "super user" or other privileges for use as authorization, or to
+ ensure specific code paths can only be access for a given scope.
+
+ It is useful for logging as well as for scoping pubsub subscriptions and
+ broadcasts when a caller subscribes to an interface or performs a particular
+ action.
+
+ Feel free to extend the fields on this struct to fit the needs of
+ growing application requirements.
+ """
+
+ alias Chesstrainer.Accounts.User
+
+ defstruct user: nil
+
+ @doc """
+ Creates a scope for the given user.
+
+ Returns nil if no user is given.
+ """
+ def for_user(%User{} = user) do
+ %__MODULE__{user: user}
+ end
+
+ def for_user(nil), do: nil
+end
diff --git a/lib/chesstrainer/accounts/user.ex b/lib/chesstrainer/accounts/user.ex
new file mode 100644
index 0000000..39cb3e4
--- /dev/null
+++ b/lib/chesstrainer/accounts/user.ex
@@ -0,0 +1,188 @@
+defmodule Chesstrainer.Accounts.User do
+ use Ecto.Schema
+ import Ecto.Changeset
+
+ @primary_key {:id, :binary_id, autogenerate: true}
+ @foreign_key_type :binary_id
+ schema "users" do
+ field :email, :string
+ field :username, :string
+ field :password, :string, virtual: true, redact: true
+ field :hashed_password, :string, redact: true
+ field :role, Ecto.Enum, values: [:member, :moderator, :admin, :super_admin], default: :member
+ field :plan, Ecto.Enum, values: [:free, :premium], default: :free
+ field :confirmed_at, :utc_datetime
+ field :authenticated_at, :utc_datetime, virtual: true
+
+ timestamps(type: :utc_datetime)
+ end
+
+ @doc """
+ A user changeset for registration.
+
+ It requires an email, a username and a password, and sets no role or plan:
+ those are programmatic values that only the promote task may change.
+
+ ## Options
+
+ * `:validate_unique` - Set to false if you don't want to validate the
+ uniqueness of the email and username, useful when displaying live
+ validations. Defaults to `true`.
+ * `:hash_password` - Hashes the password when true. Defaults to `true`.
+ """
+ def registration_changeset(user, attrs, opts \\ []) do
+ user
+ |> cast(attrs, [:email, :username, :password])
+ |> validate_email(opts)
+ |> validate_username(opts)
+ |> validate_confirmation(:password, message: "does not match password")
+ |> validate_password(opts)
+ end
+
+ @doc """
+ A user changeset for changing the role.
+
+ The role is programmatic and must never be cast from user-supplied params.
+ """
+ def role_changeset(user, attrs) do
+ user
+ |> cast(attrs, [:role])
+ |> validate_required([:role])
+ end
+
+ @doc """
+ A user changeset for registering or changing the email.
+
+ It requires the email to change otherwise an error is added.
+
+ ## Options
+
+ * `:validate_unique` - Set to false if you don't want to validate the
+ uniqueness of the email, useful when displaying live validations.
+ Defaults to `true`.
+ """
+ def email_changeset(user, attrs, opts \\ []) do
+ user
+ |> cast(attrs, [:email])
+ |> validate_email(opts)
+ end
+
+ defp validate_email(changeset, opts) do
+ changeset =
+ changeset
+ |> validate_required([:email])
+ |> validate_format(:email, ~r/^[^@,;\s]+@[^@,;\s]+$/,
+ message: "must have the @ sign and no spaces"
+ )
+ |> validate_length(:email, max: 160)
+
+ if Keyword.get(opts, :validate_unique, true) do
+ changeset
+ |> unsafe_validate_unique(:email, Chesstrainer.Repo)
+ |> unique_constraint(:email)
+ |> validate_email_changed()
+ else
+ changeset
+ end
+ end
+
+ defp validate_username(changeset, opts) do
+ changeset =
+ changeset
+ |> validate_required([:username])
+ |> validate_length(:username, min: 3, max: 30)
+ |> validate_format(:username, ~r/\A[a-zA-Z0-9_]+\z/,
+ message: "only letters, numbers and underscores"
+ )
+
+ if Keyword.get(opts, :validate_unique, true) do
+ changeset
+ |> unsafe_validate_unique(:username, Chesstrainer.Repo)
+ |> unique_constraint(:username)
+ else
+ changeset
+ end
+ end
+
+ defp validate_email_changed(changeset) do
+ if get_field(changeset, :email) && get_change(changeset, :email) == nil do
+ add_error(changeset, :email, "did not change")
+ else
+ changeset
+ end
+ end
+
+ @doc """
+ A user changeset for changing the password.
+
+ It is important to validate the length of the password, as long passwords may
+ be very expensive to hash for certain algorithms.
+
+ ## Options
+
+ * `:hash_password` - Hashes the password so it can be stored securely
+ in the database and ensures the password field is cleared to prevent
+ leaks in the logs. If password hashing is not needed and clearing the
+ password field is not desired (like when using this changeset for
+ validations on a LiveView form), this option can be set to `false`.
+ Defaults to `true`.
+ """
+ def password_changeset(user, attrs, opts \\ []) do
+ user
+ |> cast(attrs, [:password])
+ |> validate_confirmation(:password, message: "does not match password")
+ |> validate_password(opts)
+ end
+
+ defp validate_password(changeset, opts) do
+ changeset
+ |> validate_required([:password])
+ |> validate_length(:password, min: 12, max: 72)
+ # Examples of additional password validation:
+ # |> validate_format(:password, ~r/[a-z]/, message: "at least one lower case character")
+ # |> validate_format(:password, ~r/[A-Z]/, message: "at least one upper case character")
+ # |> validate_format(:password, ~r/[!?@#$%^&*_0-9]/, message: "at least one digit or punctuation character")
+ |> maybe_hash_password(opts)
+ end
+
+ defp maybe_hash_password(changeset, opts) do
+ hash_password? = Keyword.get(opts, :hash_password, true)
+ password = get_change(changeset, :password)
+
+ if hash_password? && password && changeset.valid? do
+ changeset
+ # If using Bcrypt, then further validate it is at most 72 bytes long
+ |> validate_length(:password, max: 72, count: :bytes)
+ # Hashing could be done with `Ecto.Changeset.prepare_changes/2`, but that
+ # would keep the database transaction open longer and hurt performance.
+ |> put_change(:hashed_password, Bcrypt.hash_pwd_salt(password))
+ |> delete_change(:password)
+ else
+ changeset
+ end
+ end
+
+ @doc """
+ Confirms the account by setting `confirmed_at`.
+ """
+ def confirm_changeset(user) do
+ now = DateTime.utc_now(:second)
+ change(user, confirmed_at: now)
+ end
+
+ @doc """
+ Verifies the password.
+
+ If there is no user or the user doesn't have a password, we call
+ `Bcrypt.no_user_verify/0` to avoid timing attacks.
+ """
+ def valid_password?(%Chesstrainer.Accounts.User{hashed_password: hashed_password}, password)
+ when is_binary(hashed_password) and byte_size(password) > 0 do
+ Bcrypt.verify_pass(password, hashed_password)
+ end
+
+ def valid_password?(_, _) do
+ Bcrypt.no_user_verify()
+ false
+ end
+end
diff --git a/lib/chesstrainer/accounts/user_notifier.ex b/lib/chesstrainer/accounts/user_notifier.ex
new file mode 100644
index 0000000..c78da1d
--- /dev/null
+++ b/lib/chesstrainer/accounts/user_notifier.ex
@@ -0,0 +1,39 @@
+defmodule Chesstrainer.Accounts.UserNotifier do
+ import Swoosh.Email
+
+ alias Chesstrainer.Mailer
+
+ # Delivers the email using the application mailer.
+ defp deliver(recipient, subject, body) do
+ email =
+ new()
+ |> to(recipient)
+ |> from({"Chesstrainer", "contact@example.com"})
+ |> subject(subject)
+ |> text_body(body)
+
+ with {:ok, _metadata} <- Mailer.deliver(email) do
+ {:ok, email}
+ end
+ end
+
+ @doc """
+ Deliver instructions to update a user email.
+ """
+ def deliver_update_email_instructions(user, url) do
+ deliver(user.email, "Update email instructions", """
+
+ ==============================
+
+ Hi #{user.email},
+
+ You can change your email by visiting the URL below:
+
+ #{url}
+
+ If you didn't request this change, please ignore this.
+
+ ==============================
+ """)
+ end
+end
diff --git a/lib/chesstrainer/accounts/user_token.ex b/lib/chesstrainer/accounts/user_token.ex
new file mode 100644
index 0000000..5c94377
--- /dev/null
+++ b/lib/chesstrainer/accounts/user_token.ex
@@ -0,0 +1,127 @@
+defmodule Chesstrainer.Accounts.UserToken do
+ use Ecto.Schema
+ import Ecto.Query
+ alias Chesstrainer.Accounts.UserToken
+
+ @hash_algorithm :sha256
+ @rand_size 32
+
+ @change_email_validity_in_days 7
+ @session_validity_in_days 14
+
+ @primary_key {:id, :binary_id, autogenerate: true}
+ @foreign_key_type :binary_id
+ schema "users_tokens" do
+ field :token, :binary
+ field :context, :string
+ field :sent_to, :string
+ field :authenticated_at, :utc_datetime
+ belongs_to :user, Chesstrainer.Accounts.User
+
+ timestamps(type: :utc_datetime, updated_at: false)
+ end
+
+ @doc """
+ Generates a token that will be stored in a signed place,
+ such as session or cookie. As they are signed, those
+ tokens do not need to be hashed.
+
+ The reason why we store session tokens in the database, even
+ though Phoenix already provides a session cookie, is because
+ Phoenix's default session cookies are not persisted, they are
+ simply signed and potentially encrypted. This means they are
+ valid indefinitely, unless you change the signing/encryption
+ salt.
+
+ Therefore, storing them allows individual user
+ sessions to be expired. The token system can also be extended
+ to store additional data, such as the device used for logging in.
+ You could then use this information to display all valid sessions
+ and devices in the UI and allow users to explicitly expire any
+ session they deem invalid.
+ """
+ def build_session_token(user) do
+ token = :crypto.strong_rand_bytes(@rand_size)
+ dt = user.authenticated_at || DateTime.utc_now(:second)
+ {token, %UserToken{token: token, context: "session", user_id: user.id, authenticated_at: dt}}
+ end
+
+ @doc """
+ Checks if the token is valid and returns its underlying lookup query.
+
+ The query returns the user found by the token, if any, along with the token's creation time.
+
+ The token is valid if it matches the value in the database and it has
+ not expired (after @session_validity_in_days).
+ """
+ def verify_session_token_query(token) do
+ query =
+ from token in by_token_and_context_query(token, "session"),
+ join: user in assoc(token, :user),
+ where: token.inserted_at > ago(@session_validity_in_days, "day"),
+ select: {%{user | authenticated_at: token.authenticated_at}, token.inserted_at}
+
+ {:ok, query}
+ end
+
+ @doc """
+ Builds a token and its hash to be delivered to the user's email.
+
+ The non-hashed token is sent to the user email while the
+ hashed part is stored in the database. The original token cannot be reconstructed,
+ which means anyone with read-only access to the database cannot directly use
+ the token in the application to gain access. Furthermore, if the user changes
+ their email in the system, the tokens sent to the previous email are no longer
+ valid.
+
+ Users can easily adapt the existing code to provide other types of delivery methods,
+ for example, by phone numbers.
+ """
+ def build_email_token(user, context) do
+ build_hashed_token(user, context, user.email)
+ end
+
+ defp build_hashed_token(user, context, sent_to) do
+ token = :crypto.strong_rand_bytes(@rand_size)
+ hashed_token = :crypto.hash(@hash_algorithm, token)
+
+ {Base.url_encode64(token, padding: false),
+ %UserToken{
+ token: hashed_token,
+ context: context,
+ sent_to: sent_to,
+ user_id: user.id
+ }}
+ end
+
+ @doc """
+ Checks if the token is valid and returns its underlying lookup query.
+
+ The query returns the user_token found by the token, if any.
+
+ This is used to validate requests to change the user
+ email.
+ The given token is valid if it matches its hashed counterpart in the
+ database and if it has not expired (after @change_email_validity_in_days).
+ The context must always start with "change:".
+ """
+ def verify_change_email_token_query(token, "change:" <> _ = context) do
+ case Base.url_decode64(token, padding: false) do
+ {:ok, decoded_token} ->
+ hashed_token = :crypto.hash(@hash_algorithm, decoded_token)
+
+ query =
+ from token in by_token_and_context_query(hashed_token, context),
+ where: token.inserted_at > ago(@change_email_validity_in_days, "day")
+
+ {:ok, query}
+
+ :error ->
+ :error
+ end
+ end
+
+ defp by_token_and_context_query(token, context) do
+ from UserToken, where: [token: ^token, context: ^context]
+ end
+end
diff --git a/lib/chesstrainer_web/components/layouts.ex b/lib/chesstrainer_web/components/layouts.ex
index cb46d96..d44bab5 100644
--- a/lib/chesstrainer_web/components/layouts.ex
+++ b/lib/chesstrainer_web/components/layouts.ex
@@ -5,6 +5,8 @@ defmodule ChesstrainerWeb.Layouts do
"""
use ChesstrainerWeb, :html
+ alias Chesstrainer.Accounts.Role
+
# Embed all files in layouts/* within this module.
# The default root.html.heex file contains the HTML
# skeleton of your application, namely HTML headers
@@ -51,6 +53,10 @@ defmodule ChesstrainerWeb.Layouts do
@doc """
Renders the application navbar.
"""
+ attr :current_scope, :map,
+ default: nil,
+ doc: "the current [scope](https://phoenix.hexdocs.pm/scopes.html)"
+
def navbar(assigns) do
~H"""