Raxol.Auth (Raxol v2.6.0)

Authentication and session management for Raxol.

Provides session creation, validation, and multi-factor authentication support.

Example

{:ok, session} = Raxol.Auth.create_session(user,
  expires_in: :timer.hours(24),
  renewable: true
)

case Raxol.Auth.validate_session(token) do
  {:ok, user} -> authorize(user)
  {:error, :expired} -> redirect_to_login()
end

Summary

Types

session()

Functions

create_session(user, opts \\ [])

Create a new authenticated session.

enable_mfa(user, atom)

Enable multi-factor authentication for a user.

invalidate_session(token)

Invalidate a session.

register_webauthn(user)

validate_session(token)

Validate a session token.

verify_totp(user, code)

Verify a TOTP code.

Types

session()

@type session() :: %{
  token: String.t(),
  user_id: String.t(),
  expires_at: DateTime.t(),
  renewable: boolean(),
  metadata: map()
}

Functions

create_session(user, opts \\ [])

@spec create_session(
  map(),
  keyword()
) :: {:ok, session()}

Create a new authenticated session.

Options

:expires_in - Session duration in milliseconds (default: 24 hours)
:renewable - Whether session can be renewed (default: true)
:ip_locked - Lock session to IP address (default: false)
:metadata - Additional session metadata

Example

{:ok, session} = Raxol.Auth.create_session(user,
  expires_in: :timer.hours(24),
  renewable: true
)

enable_mfa(user, atom)

@spec enable_mfa(map(), :totp | :webauthn) :: {:ok, map()}

Enable multi-factor authentication for a user.

Supported types

:totp - Time-based One-Time Password
:webauthn - WebAuthn/FIDO2

Example

{:ok, secret} = Raxol.Auth.enable_mfa(user, :totp)

invalidate_session(token)

@spec invalidate_session(String.t()) :: :ok

Invalidate a session.

register_webauthn(user)

@spec register_webauthn(map()) :: {:ok, map()}

Example

{:ok, credential} = Raxol.Auth.register_webauthn(user)

validate_session(token)

@spec validate_session(String.t()) :: {:ok, map()} | {:error, :expired | :invalid}

Validate a session token.

Example

case Raxol.Auth.validate_session(token) do
  {:ok, user} -> authorize(user)
  {:error, :expired} -> redirect_to_login()
  {:error, :invalid} -> log_security_event()
end

verify_totp(user, code)

@spec verify_totp(map(), String.t()) :: {:ok, :verified} | {:error, :invalid}

Verify a TOTP code.

Example

{:ok, :verified} = Raxol.Auth.verify_totp(user, "123456")