Helper functions for account management.

This module provides helper functions for typical account management functions, such as registration, authentication, and password change.

To use these functions, you need create required database tables and Ecto schemas, and provide accounts configuration.

Database and Ecto

Two database tables are required: one which holds the accounts, and another for managing one-time account tokens.

The account tables must contain a login field and a password hash field. Both fields should be of type strings, and set to null: false. A unique constraint should exist on the login field.

There are no rules for the names of the accounts table and these required fields. For example, the table can be named users, and the login field can be named email. Finally, this table can contain arbitrary additional data (e.g. first and last name)

The tokens table can bear arbitrary name, but the list of fields and their names is more restrictive. You can create this table with the following migration:

create table(:tokens, primary_key: false) do
  add :id, :uuid, primary_key: true
  add :hash, :binary, null: false
  add :type, :string, null: false
  add :used_at, :utc_datetime
  add :expires_at, :utc_datetime, null: false
  add :account_id, references(:accounts, type: :uuid), null: true
end

Note that account_id must be made nullable. The reason is that we're inserting tokens even if the account is not existing, which prevents enumeration attacks.

The Ecto schemas should mirror the database structure of these tables. Most importantly, the accounts schema should specify has_many :tokens, while the tokens schema should specify a corresponding belong_to association.

Configuration

With tables, and schemas in place, you need to define accounts configuration. It is advised to do this by defining a private function accounts_config/0 in the context module where you're implementing accounts operations:

defmodule MyProject.SomeContext do
  # ...

  defp accounts_config() do
    %{
      repo: MyProject.Repo,
      schemas: %{
        account: MyProject.Schemas.Account,
        token: MyProject.Schemas.Token
      },
      login_field: :email,
      password_hash_field: :password_hash,
      min_password_length: 6
    }
  end
end

Usage

To implement account operations, define corresponding functions in the same context module. For example:

defmodule MyProject.SomeContext do
  def create_account(params) do
    %Account{}
    # additional client fields
    |> cast(account_params, ~w(first_name last_name)a)
    |> validate_required(~w(first_name last_name)a)
    # invocation of the generic function
    |> Accounts.create(account_params.email, account_params.password, accounts_config())
  end

  # ...
end

See documentation of individual functions, as well as VBT.Accounts.Token for details.

Tokens cleanup

By default, token entries are not removed from the database. To periodically remove them, you need to start the cleanup process. See VBT.Accounts.Token.Cleanup for details.