Dialup.Auth (Dialup v0.2.0)

Authentication helpers for Dialup applications.

Dialup separates two session concepts:

dialup_session — connection ID for UserSessionProcess (anonymous until enriched)
_dialup_user_token — opaque auth token resolved to current_user

Configure an accounts module on the app or plug:

use Dialup,
  auth_accounts: MyApp.Accounts

plugs: [{Dialup.Auth.Plug, accounts: MyApp.Accounts}]

Summary

Functions

accounts_module(app_module)

Returns the configured accounts module for an app, if any.

build_layout_session(session, arg2)

Merges auth context into an existing session map.

cookie_opts(conn)

Returns cookie options aligned with the app's :secure_cookies setting.

csrf_cookie()

Cookie name for CSRF double-submit.

csrf_token(conn)

Returns a CSRF token for forms, setting the cookie when needed.

current_user(conn)

Resolves the current user from conn assigns (set by Dialup.Auth.Plug).

fetch_current_user(conn, accounts_module)

Fetches the current user from assigns or cookies.

initial_session(user)

Seeds layout session with current_user before layout.mount runs.

log_in_user(conn, user, accounts_module)

Logs a user in by issuing the auth cookie and rotating dialup_session.

log_out_user(conn, accounts_module)

Logs a user out, clearing the auth cookie and rotating dialup_session.

public_user(user)

Projects a user for Dialup session / agent_state (no secrets).

require_authenticated_user(conn, login_path \\ "/log_in")

Halts with a redirect when no user is present.

resolve_conn_user(conn, app_module)

Resolves the current user from plug assigns or cookies.

rotate_dialup_session(conn)

Rotates the anonymous connection session cookie (session fixation mitigation).

safe_redirect_path(path)

Returns a same-origin relative path or / when the target is unsafe.

session_token(conn)

Returns the opaque auth session token from a connection's cookies.

session_token_from_cookies(cookies)

Returns the opaque auth session token from cookies, if present.

user_from_cookies(cookies, accounts_module)

Resolves a user from request cookies using the accounts module.

user_token_cookie()

Cookie name for the opaque user session token.

valid_csrf?(conn, params)

Validates a CSRF token from form params against the cookie.

Functions

accounts_module(app_module)

@spec accounts_module(atom()) :: module() | nil

Returns the configured accounts module for an app, if any.

build_layout_session(session, arg2)

@spec build_layout_session(map(), map()) :: map()

Merges auth context into an existing session map.

cookie_opts(conn)

@spec cookie_opts(Plug.Conn.t()) :: keyword()

Returns cookie options aligned with the app's :secure_cookies setting.

csrf_cookie()

Cookie name for CSRF double-submit.

csrf_token(conn)

@spec csrf_token(Plug.Conn.t()) :: {Plug.Conn.t(), binary()}

Returns a CSRF token for forms, setting the cookie when needed.

current_user(conn)

@spec current_user(Plug.Conn.t()) :: map() | struct() | nil

Resolves the current user from conn assigns (set by Dialup.Auth.Plug).

fetch_current_user(conn, accounts_module)

@spec fetch_current_user(Plug.Conn.t(), module()) ::
  {Plug.Conn.t(), map() | struct() | nil}

Fetches the current user from assigns or cookies.

initial_session(user)

@spec initial_session(map() | struct() | nil) :: map()

Seeds layout session with current_user before layout.mount runs.

log_in_user(conn, user, accounts_module)

@spec log_in_user(Plug.Conn.t(), map() | struct(), module()) :: Plug.Conn.t()

Logs a user in by issuing the auth cookie and rotating dialup_session.

log_out_user(conn, accounts_module)

@spec log_out_user(Plug.Conn.t(), module()) :: Plug.Conn.t()

Logs a user out, clearing the auth cookie and rotating dialup_session.

public_user(user)

@spec public_user(map() | struct() | nil) :: map() | nil

Projects a user for Dialup session / agent_state (no secrets).

require_authenticated_user(conn, login_path \\ "/log_in")

@spec require_authenticated_user(Plug.Conn.t(), binary()) :: Plug.Conn.t()

Halts with a redirect when no user is present.

resolve_conn_user(conn, app_module)

@spec resolve_conn_user(Plug.Conn.t(), atom()) :: map() | struct() | nil

Resolves the current user from plug assigns or cookies.

Matches HTTP page rendering: prefers dialup_current_user from Dialup.Auth.Plug, then falls back to cookie resolution when auth_accounts is configured.

rotate_dialup_session(conn)

@spec rotate_dialup_session(Plug.Conn.t()) :: Plug.Conn.t()

Rotates the anonymous connection session cookie (session fixation mitigation).

safe_redirect_path(path)

@spec safe_redirect_path(term()) :: binary()

Returns a same-origin relative path or / when the target is unsafe.

session_token(conn)

@spec session_token(Plug.Conn.t()) :: binary() | nil

Returns the opaque auth session token from a connection's cookies.

session_token_from_cookies(cookies)

@spec session_token_from_cookies(map()) :: binary() | nil

Returns the opaque auth session token from cookies, if present.

user_from_cookies(cookies, accounts_module)

@spec user_from_cookies(map(), module()) :: map() | struct() | nil

Resolves a user from request cookies using the accounts module.

user_token_cookie()

Cookie name for the opaque user session token.

valid_csrf?(conn, params)

@spec valid_csrf?(Plug.Conn.t(), map()) :: boolean()

Validates a CSRF token from form params against the cookie.