Tango.Auth (tango v0.1.2)

Copy Markdown View Source

Main OAuth2 flow orchestrator.

Handles complete OAuth2 authorization code flow with PKCE support, session management, and token exchange with automatic audit logging.

Summary

Types

auth_url_result()
cleanup_result()
connection_result()
session_result()

Functions

authorize_url(session_token, opts \\ [])

Generates OAuth authorization URL with PKCE support.

authorize_url_with_scopes(session_token, redirect_uri, scopes)

Generate authorization URL with optional scopes.

build_callback_url(conn)

Build OAuth callback URL from connection, handling proxy headers.

build_connection_response(connection, provider, access_token)

Build connection response for OAuth callbacks.

build_https_callback_url(conn)

Build HTTPS callback URL from connection.

classify_oauth_error(arg1)

Classify OAuth error types.

cleanup_expired_sessions()

Cleans up expired OAuth sessions.

create_session(provider_name, tenant_id, opts \\ [])

Creates a new OAuth session for provider and tenant.

decode_state_safely(state)

Safely decode OAuth state parameter.

decode_state_with_tenant(encoded_state)
exchange_code(state, authorization_code, tenant_id, opts)

Exchanges authorization code for access token.

generate_callback_html(code, state, error, error_description, exchange_result)

Generate OAuth callback HTML page for popup flows.

get_session(session_token)

Gets a valid (non-expired) session by token.

html_escape_json(json_string)
log_oauth_callback_error(state, error, error_description)

Log OAuth callback errors with audit trail.

map_oauth_error_code(arg1)

Map OAuth error codes to atoms.

parse_scopes(scopes)

Parse OAuth scopes from various formats.

perform_callback_exchange(conn, code, state)

Perform OAuth callback exchange for popup flows.

Types

auth_url_result()

@type auth_url_result() :: {:ok, String.t()} | {:error, atom()}

cleanup_result()

@type cleanup_result() :: {:ok, non_neg_integer()} | {:error, atom()}

connection_result()

@type connection_result() ::
  {:ok,
   %Tango.Schemas.Connection{
     __meta__: term(),
     access_token: term(),
     auth_failures: term(),
     auto_refresh_enabled: term(),
     connection_config: term(),
     expires_at: term(),
     granted_scopes: term(),
     id: term(),
     inserted_at: term(),
     last_auth_failure: term(),
     last_refresh_failure: term(),
     last_used_at: term(),
     lock_version: term(),
     metadata: term(),
     next_refresh_at: term(),
     provider: term(),
     provider_id: term(),
     raw_payload: term(),
     refresh_attempts: term(),
     refresh_exhausted: term(),
     refresh_token: term(),
     status: term(),
     tenant_id: term(),
     token_type: term(),
     updated_at: term()
   }}
  | {:error, atom()}

session_result()

@type session_result() ::
  {:ok,
   %Tango.Schemas.OAuthSession{
     __meta__: term(),
     code_verifier: term(),
     expires_at: term(),
     id: term(),
     inserted_at: term(),
     metadata: term(),
     provider: term(),
     provider_id: term(),
     redirect_uri: term(),
     scopes: term(),
     session_token: term(),
     state: term(),
     tenant_id: term(),
     updated_at: term()
   }}
  | {:error, atom()}

Functions

authorize_url(session_token, opts \\ [])

@spec authorize_url(
  String.t(),
  keyword()
) :: auth_url_result()

Generates OAuth authorization URL with PKCE support.

Examples

iex> authorize_url("session_token_123", redirect_uri: "https://app.com/callback")
{:ok, "https://github.com/login/oauth/authorize?client_id=..."}

iex> authorize_url("invalid_token", redirect_uri: "https://app.com/callback")
{:error, :session_not_found}

authorize_url_with_scopes(session_token, redirect_uri, scopes)

Generate authorization URL with optional scopes.

Uses session/provider defaults when scopes list is empty, otherwise uses explicit scopes provided.

build_callback_url(conn)

Build OAuth callback URL from connection, handling proxy headers.

build_connection_response(connection, provider, access_token)

Build connection response for OAuth callbacks.

build_https_callback_url(conn)

Build HTTPS callback URL from connection.

classify_oauth_error(arg1)

Classify OAuth error types.

cleanup_expired_sessions()

@spec cleanup_expired_sessions() :: cleanup_result()

Cleans up expired OAuth sessions.

Should be called periodically to prevent table bloat.

Examples

iex> cleanup_expired_sessions()
{:ok, 5}  # 5 sessions cleaned up

create_session(provider_name, tenant_id, opts \\ [])

@spec create_session(String.t(), String.t(), keyword()) :: session_result()

Creates a new OAuth session for provider and tenant.

Generates secure session tokens, PKCE parameters, and CSRF state.

Examples

iex> create_session("github", "user-123")
{:ok, %OAuthSession{}}

iex> create_session("nonexistent", "user-123")
{:error, :provider_not_found}

decode_state_safely(state)

Safely decode OAuth state parameter.

decode_state_with_tenant(encoded_state)

exchange_code(state, authorization_code, tenant_id, opts)

@spec exchange_code(String.t(), String.t(), String.t(), keyword()) ::
  connection_result()

Exchanges authorization code for access token.

Validates session state, exchanges code with provider, and creates connection. SECURITY: Requires tenant_id for multi-tenant isolation.

Examples

iex> exchange_code("state_123", "auth_code_456", "tenant-123", redirect_uri: "https://app.com/callback")
{:ok, %Connection{}}

iex> exchange_code("invalid_state", "code", "tenant-123", redirect_uri: "https://app.com/callback")
{:error, :invalid_state}

iex> exchange_code("state_123", "code", "wrong-tenant", redirect_uri: "https://app.com/callback")
{:error, :tenant_mismatch}

generate_callback_html(code, state, error, error_description, exchange_result)

Generate OAuth callback HTML page for popup flows.

get_session(session_token)

@spec get_session(String.t()) :: session_result()

Gets a valid (non-expired) session by token.

Examples

iex> get_session("valid_token")
{:ok, %OAuthSession{}}

iex> get_session("expired_token")
{:error, :session_expired}

html_escape_json(json_string)

log_oauth_callback_error(state, error, error_description)

Log OAuth callback errors with audit trail.

map_oauth_error_code(arg1)

Map OAuth error codes to atoms.

parse_scopes(scopes)

Parse OAuth scopes from various formats.

perform_callback_exchange(conn, code, state)

Perform OAuth callback exchange for popup flows.