Ingot.Auth (Ingot v0.1.0)

View Source

Authentication and session management for Ingot.

Provides functions for creating and validating sessions, checking roles, and managing user authentication state.

Session Management

Sessions are stored in Phoenix encrypted cookies and include:

  • User ID
  • Email
  • Roles
  • Expiration timestamp

Role Hierarchy

The :admin role grants all permissions. When checking roles, admin users are considered to have all roles.

Examples

# Create a session
user = %{id: "user_123", email: "test@example.com", roles: [:labeler]}
session_data = Auth.create_session(user)

# Validate a session
case Auth.validate_session(session_data) do
  {:ok, session} -> # Session is valid
  {:error, :expired} -> # Session has expired
  {:error, :invalid_session} -> # Session is malformed
end

# Check roles
Auth.has_role?([:labeler, :admin], :labeler) #=> true
Auth.has_role?([:admin], :auditor) #=> true (admin has all roles)

Summary

Types

session_data()
user()

Functions

create_session(user, opts \\ [])

Create session data for a user.

has_role?(roles, required_role)

Check if a user has a specific role.

validate_session(session_data)

Validate session data.

Types

session_data()

@type session_data() :: %{
  user_id: String.t(),
  user_email: String.t(),
  roles: [atom()],
  expires_at: integer()
}

user()

@type user() :: %{id: String.t(), email: String.t(), roles: [atom()]}

Functions

create_session(user, opts \\ [])

@spec create_session(
  user(),
  keyword()
) :: session_data()

Create session data for a user.

Options

  • :ttl_hours - Session time-to-live in hours (default: 24)

Examples

iex> user = %{id: "user_123", email: "test@example.com", roles: [:labeler]}
iex> session = Auth.create_session(user)
iex> session.user_id
"user_123"

has_role?(roles, required_role)

@spec has_role?([atom()], atom()) :: boolean()

Check if a user has a specific role.

The :admin role grants all permissions, so admin users will return true for any role check.

Examples

iex> Auth.has_role?([:labeler], :labeler)
true

iex> Auth.has_role?([:labeler], :admin)
false

iex> Auth.has_role?([:admin], :labeler)
true

validate_session(session_data)

@spec validate_session(map() | nil) ::
  {:ok, session_data()} | {:error, :expired | :invalid_session}

Validate session data.

Returns {:ok, session_data} if the session is valid and not expired. Returns {:error, :expired} if the session has expired. Returns {:error, :invalid_session} if the session is malformed.

Examples

iex> session = %{user_id: "123", user_email: "test@example.com", roles: [:labeler], expires_at: future_timestamp}
iex> Auth.validate_session(session)
{:ok, %{user_id: "123", ...}}

iex> expired_session = %{user_id: "123", expires_at: past_timestamp}
iex> Auth.validate_session(expired_session)
{:error, :expired}