defmodule Pow.Store.CredentialsCache do
@moduledoc """
Default module for credentials session storage.
A key (session id) is used to store, fetch, or delete credentials. The
credentials are expected to take the form of
`{credentials, session_metadata}`, where session metadata is data exclusive
to the session id.
This module also adds two utility methods:
* `users/2` - to list all current users
* `sessions/2` - to list all current sessions
The `:ttl` should be maximum 30 minutes per
[OWASP recommendations](https://cheatsheetseries.owasp.org/cheatsheets/Session_Management_Cheat_Sheet.html#session-expiration).
A warning will be output for any sessions created with a longer TTL.
## Custom credentials cache module
Pow may use the utility methods in this module. To ensure all required
methods has been implemented in a custom credentials cache module, the
`@behaviour` of this module should be used:
defmodule MyApp.CredentialsStore do
use Pow.Store.Base,
ttl: :timer.minutes(30),
namespace: "credentials"
@behaviour Pow.Store.CredentialsCache
@impl Pow.Store.CredentialsCache
def users(config, struct) do
# ...
end
@impl Pow.Store.CredentialsCache
def put(config, key, value) do
# ...
end
end
## Configuration options
* `:reload` - boolean value for whether the user object should be loaded
from the context. Defaults false.
"""
alias Pow.{Config, Operations, Store.Base}
@callback users(Base.config(), module()) :: [any()]
@callback sessions(Base.config(), map()) :: [binary()]
@callback put(Base.config(), binary(), {map(), list()}) :: :ok
# Per https://cheatsheetseries.owasp.org/cheatsheets/Session_Management_Cheat_Sheet.html#session-expiration
@recommended_max_idle_timeout :timer.minutes(30)
use Base,
ttl: :timer.minutes(30),
namespace: "credentials"
@doc """
List all user for a certain user struct.
Sessions for a user can be looked up with `sessions/3`.
"""
@spec users(Base.config(), module()) :: [any()]
def users(config, struct) do
config
|> Base.all(backend_config(config), [struct, :user, :_])
|> Enum.map(fn {[^struct, :user, _id], user} ->
user
end)
end
@doc """
List all existing sessions for the user fetched from the backend store.
"""
@spec sessions(Base.config(), map()) :: [binary()]
def sessions(config, user), do: fetch_sessions(config, backend_config(config), user)
# TODO: Refactor by 1.1.0
defp fetch_sessions(config, backend_config, user) do
{struct, id} = user_to_struct_id!(user, [])
config
|> Base.all(backend_config, [struct, :user, id, :session, :_])
|> Enum.map(fn {[^struct, :user, ^id, :session, session_id], _value} ->
session_id
end)
end
@doc """
Add user credentials with the session id to the backend store.
The credentials are expected to be in the format of
`{credentials, metadata}`.
This following three key-value will be inserted:
- `{session_id, {[user_struct, :user, user_id], metadata}}`
- `{[user_struct, :user, user_id], user}`
- `{[user_struct, :user, user_id, :session, session_id], inserted_at}`
If metadata has `:fingerprint` any active sessions for the user with the same
`:fingerprint` in metadata will be deleted.
"""
@spec put(Base.config(), binary(), {map(), list()}) :: :ok
def put(config, session_id, {user, metadata}) do
{struct, id} = user_to_struct_id!(user, [])
user_key = [struct, :user, id]
session_key = [struct, :user, id, :session, session_id]
records = [
{session_id, {user_key, metadata}},
{user_key, user},
{session_key, :os.system_time(:millisecond)}
]
delete_user_sessions_with_fingerprint(config, user, metadata)
backend_config =
config
|> backend_config()
|> warn_maximum_timeout()
Base.put(config, backend_config, records)
end
defp warn_maximum_timeout(config) do
if Config.get(config, :ttl, 0) > @recommended_max_idle_timeout do
IO.warn(
"""
warning: `:ttl` value for sessions should be no longer than #{round(@recommended_max_idle_timeout / 1_000 / 60)} minutes to prevent session hijack, please consider lowering the value
""")
end
config
end
@doc """
Delete the user credentials data from the backend store.
This following two key-value will be deleted:
- `{session_id, {[user_struct, :user, user_id], metadata}}`
- `{[user_struct, :user, user_id, :session, session_id], inserted_at}`
The `{[user_struct, :user, user_id], user}` key-value is expected to expire
when reaching its TTL.
"""
@impl true
def delete(config, session_id) do
backend_config = backend_config(config)
case Base.get(config, backend_config, session_id) do
{[struct, :user, key_id], _metadata} ->
session_key = [struct, :user, key_id, :session, session_id]
Base.delete(config, backend_config, session_id)
Base.delete(config, backend_config, session_key)
# TODO: Remove by 1.1.0
{user, _metadata} when is_map(user) ->
Base.delete(config, backend_config, session_id)
:not_found ->
:ok
end
end
@doc """
Fetch user credentials from the backend store from session id.
"""
@impl true
@spec get(Base.config(), binary()) :: {map(), list()} | nil | :not_found
def get(config, session_id) do
backend_config = backend_config(config)
with {user_key, metadata} when is_list(user_key) <- Base.get(config, backend_config, session_id),
user when is_map(user) <- Base.get(config, backend_config, user_key),
user when not is_nil(user) <- maybe_reload(user, config) do
{user, metadata}
else
# TODO: Remove by 1.1.0
{user, metadata} when is_map(user) -> {user, metadata}
:not_found -> :not_found
nil -> nil
end
end
defp maybe_reload(user, config) do
# TODO: By 1.1.0 set this to `true` and update docs
case Keyword.get(config, :reload, false) do
true -> Operations.reload(user, fetch_pow_config!(config))
_any -> user
end
end
defp fetch_pow_config!(config), do: Keyword.get(config, :pow_config) || raise "No `:pow_config` value found in the store config."
defp user_to_struct_id!(%mod{} = user, config) do
key_values =
user
|> fetch_primary_key_values!(config)
|> Enum.sort(&elem(&1, 0) < elem(&2, 0))
|> case do
[id: id] -> id
clauses -> clauses
end
{mod, key_values}
end
defp user_to_struct_id!(_user, _config), do: raise "Only structs can be stored as credentials"
defp fetch_primary_key_values!(user, config) do
pow_config = Keyword.get(config, :pow_config)
user
|> Operations.fetch_primary_key_values(pow_config)
|> case do
{:error, error} -> raise error
{:ok, clauses} -> clauses
end
end
defp delete_user_sessions_with_fingerprint(config, user, metadata) do
case Keyword.get(metadata, :fingerprint) do
nil -> :ok
fingerprint -> do_delete_user_sessions_with_fingerprint(config, user, fingerprint)
end
end
defp do_delete_user_sessions_with_fingerprint(config, user, fingerprint) do
backend_config = backend_config(config)
config
|> sessions(user)
|> Enum.each(fn session_id ->
with {_user_key, metadata} when is_list(metadata) <- Base.get(config, backend_config, session_id),
^fingerprint <- Keyword.get(metadata, :fingerprint) do
delete(config, session_id)
end
end)
end
# TODO: Remove by 1.1.0
@doc false
@deprecated "Use `users/2` or `sessions/2` instead"
def user_session_keys(config, backend_config, struct) do
config
|> Base.all(backend_config, [struct, :user, :_, :session, :_])
|> Enum.map(fn {key, _value} ->
key
end)
end
# TODO: Remove by 1.1.0
@doc false
@deprecated "Use `sessions/2` instead"
def sessions(config, backend_config, user), do: fetch_sessions(config, backend_config, user)
end
