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 the server refused to
      %% refresh it (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),
 
      %% Report the organizations the server says this session has to
      %% complete SSO or 2FA verification for (optional). Called
      %% after every token grant that carried a readable set, with the empty
      %% list when there are none, so the build tool always holds the current
      %% set. It is not told which of them the running command needs; deciding
      %% that is the build tool's job.
      organization_reauth => fun(([map()]) -> ok),
 
      %% Outcome of the last Workload Identity exchange for a repository
      %% (optional, both or neither). Hex.pm organization repositories are
      %% only fetched with a workload identity when the build tool keeps the
      %% outcome, so concurrent and later requests reuse a token, or the
      %% failure, instead of each exchanging a new OIDC token. Keep it in
      %% memory for the rest of the run, the token expires in minutes.
      get_workload_identity_token => fun((RepoName :: binary()) ->
          {ok, #{access_token := binary(), expires_at := integer()}}
          | {error, workload_identity_error()}
          | error),
      persist_workload_identity_token => fun((RepoName :: binary(),
          {ok, #{access_token := binary(), expires_at := integer()}}
          | {error, workload_identity_error()}) -> 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
4. Workload Identity token (for "hexpm:org" organizations)

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():

• 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.

Workload Identity

Workload Identity, sometimes also known as "Trusted Publishing", lets a supported CI job (currently GitHub Actions) publish and fetch without a stored key. workload_identity_auth/2 exchanges the job's OIDC token for API auth scoped to one package. See its documentation for details.

A repository request to a Hex.pm organization ("hexpm:org") that resolves no other credentials exchanges the job's OIDC token for a token scoped to the organization's repository, when the build tool provides the get_workload_identity_token and persist_workload_identity_token callbacks. A failed exchange isn't repeated in the same run.