Authentication handling with callback functions for build-tool-specific operations.

This module provides generic authentication handling that allows both rebar3 and Elixir Hex (and future build tools) to share the common auth logic while customizing prompting, persistence, and configuration retrieval.

Callbacks

Callbacks are provided via the cli_auth_callbacks key in the config map. All callbacks below are required unless marked optional:

  #{
      %% Auth configuration for a specific repo
      get_auth_config => fun((RepoName :: binary()) ->
          #{api_key => binary(),
            auth_key => binary(),
            oauth_exchange => boolean(),
            oauth_exchange_url => binary()} | undefined),
 
      %% Global OAuth tokens - storage and retrieval
      get_oauth_tokens => fun(() -> {ok, #{access_token := binary(),
                                           refresh_token => binary(),
                                           expires_at := integer()}} | error),
      persist_oauth_tokens => fun((Scope :: global | binary(),
                                   AccessToken :: binary(),
                                   RefreshToken :: binary() | undefined,
                                   ExpiresAt :: integer()) -> ok),
 
      %% Invalidate the stored global OAuth token after it expired and could
      %% not be refreshed (optional). Lets the build tool drop the unusable
      %% token so concurrent and subsequent callers stop retrying the doomed
      %% refresh, and warn the user. Invoked at most once per resolution, while
      %% holding the token-refresh lock.
      clear_oauth_tokens => fun(() -> ok),
 
      %% User interaction
      prompt_otp => fun((Message :: binary()) -> {ok, OtpCode :: binary()} | cancelled),
      should_authenticate => fun((Reason :: no_credentials | token_refresh_failed) -> boolean()),
 
      %% OAuth client configuration
      get_client_id => fun(() -> binary())
  }

Auth Resolution Order

For API calls:

1. Per-repo api_key from config (with optional OAuth exchange for hex.pm)
2. Parent repo api_key (for "hexpm:org" organizations)
3. Global OAuth token (refreshed if expired)
4. Device auth flow (for write operations only)

For repo calls:

1. Per-repo auth_key with optional OAuth exchange (default true for hex.pm)
2. Parent repo auth_key
3. Global OAuth token

OAuth Exchange

For hex.pm URLs, api_key and auth_key are exchanged for short-lived OAuth tokens via the client credentials grant. This behavior can be controlled per-repo via the oauth_exchange option in the repo config (defaults to true for hex.pm).

Auth Context

Internally, authentication resolution tracks context via auth_context():

• source - Where the credentials came from (env, config, or oauth)
• has_refresh_token - Whether token refresh is possible on 401

Token Format

OAuth access tokens are automatically prefixed with <<"Bearer ">> when used as api_key or repo_key in the config.