Introduce `hex_auth` module by maennchen · Pull Request #178 · hexpm/hex_core

maennchen · 2026-04-13T22:40:57Z

Base Module organizing Repo / API Auth Management.

This PR is WIP. I'm exploring how it could look.

Implementation PRs:

ericmj

I am not sure this fits in hex_core. It's very specific to implementing OAuth for a CLI, specifically to how Hex and rebar3 work with config resolution order and environment variables. hex_core should be more generic than that, for example you should be able to use it in web services, like hexdocs or hexdiff, and this wouldn't fit for that.

I understand we want to avoid auth logic between Hex and rebar3 if it's mostly shared, but I am not sure it fits in hex_core.

maennchen · 2026-04-14T09:07:02Z

@ericmj I'm aware that this is very much scoped towards CLIs. Is there a reason to not include a CLI only module into hex_core?

I would love to be able to reuse the auth logic that is frankly quite complicated between our clients. That way we can minimize maintenance work, are able to roll out features more quickly and also ensure better compatibility.

ericmj · 2026-04-14T20:08:42Z

I'm aware that this is very much scoped towards CLIs. Is there a reason to not include a CLI only module into hex_core?

I think we can do that if we make that clear in the docs and maybe scoping under a hex_cli namespace as hex_cli_auth.

I am still am bit hesitant at keeping it so close to how Hex and Rebar3 works with environment variables and config resolution. Would every CLI client want to do it the same way?

maennchen · 2026-04-14T21:05:30Z

I think we can do that if we make that clear in the docs and maybe scoping under a hex_cli namespace as hex_cli_auth.

That sounds like a reasonable name.

I am still am bit hesitant at keeping it so close to how Hex and Rebar3 works with environment variables and config resolution. Would every CLI client want to do it the same way?

Let's not do env variables. In the case of rebar, that would be better handled in the rebar_hex_repos module.

wojtekmach

This looks solid and well tested, I left some comments below.

wojtekmach · 2026-04-16T11:47:06Z

        case proplists:get_value(name, Opts) of
-            undefined -> Params0;
-            Name -> Params0#{<<"name">> => Name}
+            undefined -> get_hostname();


just double-checking, why do we need to send user's hostname?

This is passed here to identify the device code reuqest:

https://github.com/hexpm/hexpm/blob/main/lib/hexpm/oauth/device_codes.ex#L33

We already do this presently: https://github.com/hexpm/hex/blob/main/lib/mix/tasks/hex.ex#L141

wojtekmach · 2026-04-16T12:17:00Z

+%% hex_cli_auth:with_api(Callbacks, write, Config, fun(C) ->
+%%     hex_api_release:publish(C, Tarball)
+%% end, [{optional, false}, {auth_inline, true}]).


I'm curious about callbacks-based API and wrapping user code (here, hex_api_release:publish/2) in fun vs a more traditional imperative API. Are we wrapping user code in a fun because we might be doing multiple requests? Or we wanna trigger lifecycle hooks when we exit user code? (Or both?) Maybe just as an exercise worth exploring how an imperative API without callbacks would look like--or such is impossible, i.e. misses the point of having this module in the first place?

Yes, this will possibly do multiple requests. For example to ask for an OTP token.

ericmj · 2026-04-17T19:02:40Z

One thing we have think about this approach, where we model hex_core very closely to how Hex/Rebar3 currently works.

What happens when I want to add a new feature to Hex, for example meta organizations/repos that can contain sub repos. Rebar3 might lag behind adding this feature or may not want to add it all, so now hex_cli_auth must diverge.

maennchen · 2026-04-20T09:04:08Z

@ericmj I believe that we can deal with this when we are making changes as long as we consider rebar when making them. We can choose to build it in a way where there's no trouble not implementing a new feature, make it conditional behind a flag etc. Worst case, we can choose to fork the module.

Add a high-level function that handles the complete OAuth device authorization flow: initiating authorization, prompting the user, and polling for token completion. - Add oauth_tokens/0 and device_auth_error/0 types - Handle slow_down, authorization_pending, expired_token, and access_denied responses during polling

Add config options for hex_cli_auth authentication handling: - trusted: whether the repo connection is trusted for auth_key usage - oauth_exchange: whether to exchange api_key/auth_key for OAuth tokens - oauth_exchange_url: optional custom URL for OAuth token exchange

Provides callback-based authentication for build tools (rebar3, Mix) with shared auth logic and customizable prompting/persistence. Features: - with_api/4,5 and with_repo/3,4 wrappers for authenticated requests - resolve_api_auth/3 and resolve_repo_auth/2 for credential resolution - Auth resolution order: config, per-repo keys, parent repo, OAuth - OAuth token exchange via client_credentials grant - Automatic token refresh when expired - OTP/TOTP prompt handling with retry logic - Device auth flow for interactive authentication - Support for trusted/untrusted repo connections Includes comprehensive test suite covering: - API and repo auth resolution - Trusted vs untrusted scenarios - OAuth token exchange (new, valid, expired) - OTP prompts and retries - Token refresh on 401 - Device auth flow

ericmj · 2026-05-27T21:53:18Z

+%% Resolve OAuth token with global lock to prevent concurrent refresh attempts.
+resolve_oauth_token_with_context(Callbacks, Config) ->
+    global:trans(
+        {{?MODULE, token_refresh}, self()},


Should we remove self()? Afaict this will only serialize for the current process.

My understanding of global is that we need to identify who is requesting the lock. It does not have to be a pid, but needs to be unique for each request.

https://www.erlang.org/doc/apps/kernel/global.html#t:id/0

Sorry, I think I'm wrong. I'll write a good test and see what happens.

It was correct, but [] nodes was not. I added a test specifically for it.

ericmj · 2026-05-27T21:55:14Z

+                {"cmd", ["/c", "start", "", UrlStr]}
+        end,
+    Port = open_port({spawn_executable, os:find_executable(Cmd)}, [{args, Args}]),
+    port_close(Port),


Should we immediately close here? That's not how we do it in hex, we just let the OS clean it up. I am afraid this could race since open_port is async afaik.

ericmj · 2026-05-27T21:56:00Z

+            {win32, _} ->
+                {"cmd", ["/c", "start", "", UrlStr]}
+        end,
+    Port = open_port({spawn_executable, os:find_executable(Cmd)}, [{args, Args}]),


We should handle if os:find_executable/1 cannot find an executable.

wojtekmach

Looks good to me!

wojtekmach · 2026-06-05T13:30:43Z

+with_repo(Callbacks, BaseConfig, Fun, Opts) ->
+    Optional = proplists:get_value(optional, Opts, true),
+    AuthInline = proplists:get_value(auth_inline, Opts, false),
+    case resolve_repo_auth(Callbacks, BaseConfig) of


(Callbacks, BaseConfig)

Just wondering if we should put callbacks under config?

Would users specify different functions for the same callback names in different call sites? (Even then, they could just modify Config appropriately before calling the function I suppose.) That said, config already has a bunch of stuff so I suppose it'd have to be under oauth_callbacks or similar.

I think the call sites would look something like this:

f(#{oauth_callbacks := #{should_authenticate := Callback}} = Config) -> Callback(...),

which I think is ergonomic enough and it avoids the call_callback indirection. (Nothing wrong with it of course.)

So far in each implementation I used a fixed set of callbacks.

I did not add it to config since that has the type hex_core:config() and I did not want to add it globally.

See:

https://github.com/maennchen/rebar3/blob/c423bd4a350440dbdde282d0cdd5e04652c6e437/apps/rebar/src/rebar_hex_auth.erl#L33

https://github.com/maennchen/hex/blob/e172f6bbc631ae1f14f18093906036c2cb2ef459/lib/hex/auth.ex#L38-L47

I am ok with leaving this as is.

Just mentioning in case it resonates with anyone,

I did not add it to config since that has the type hex_core:config() and I did not want to add it globally.

I think on the hex core side, the change would probably be something like this:

--- a/src/hex_core.erl +++ b/src/hex_core.erl @@ -126,7 +126,17 @@ metadata_fields => all | [binary()], trusted => boolean(), oauth_exchange => boolean(), - oauth_exchange_url => binary() | undefined + oauth_exchange_url => binary() | undefined, + oauth_callbacks => + undefined | + #{ + get_auth_config => (binary() -> ...), + get_oauth_tokens => (-> ...), + persist_oauth_tokens => (..., ..., ..., ... -> ...), + prompt_otp => (binary() -> ...), + should_authenticate => (... -> ...), + get_client_id => (-> ...) + } }. -spec default_config() -> config(). @@ -157,5 +167,6 @@ default_config() -> metadata_fields => all, trusted => true, oauth_exchange => true, - oauth_exchange_url => undefined + oauth_exchange_url => undefined, + oauth_callbacks => undefined }.

and call sites in this PR. And then in hexpm/hex, we have:

$ rg mix_hex_core.default_config lib lib/hex/repo.ex 307: :mix_hex_core.default_config() lib/hex/http.ex 14: :mix_hex_core.default_config() lib/hex/api/client.ex 6: :mix_hex_core.default_config() lib/hex/tar.ex 18: :mix_hex_core.default_config()

so I think it'd be a good forcing function to have, perhaps, a single:

defmodule Hex do def hex_core_config do %{:hex_core.default_config | ...} end end

which seems like maybe a step in the right direction, having a single place to instantiate the config and thread it through the code.

I’m coming around to the idea. I wouldn’t call them oauth_callbacks though. Possibly cli_auth_callbacks.

@ericmj What do you think?

I like those suggestions

This was referenced Apr 13, 2026

Update to use hex_auth module hexpm/hex#1143

Draft

Implement Hex Auth erlang/rebar3#3008

Draft

ericmj reviewed Apr 14, 2026

View reviewed changes

Comment thread src/hex_auth.erl Outdated

Comment thread src/hex_auth.erl Outdated

Comment thread src/hex_cli_auth.erl

maennchen force-pushed the jm/hex_auth branch 2 times, most recently from 4321c4e to e56c3db Compare April 16, 2026 11:10

wojtekmach reviewed Apr 16, 2026

View reviewed changes

maennchen force-pushed the jm/hex_auth branch 2 times, most recently from cb231fa to b8cea90 Compare April 16, 2026 12:54

maennchen mentioned this pull request Apr 16, 2026

Implement Hex Auth erlef/rebar3_hex#361

Draft

maennchen force-pushed the jm/hex_auth branch from 0775486 to 3f5ca3c Compare April 16, 2026 16:56

maennchen force-pushed the jm/hex_auth branch 2 times, most recently from e13da1b to c4c38cc Compare May 14, 2026 22:53

maennchen added 4 commits May 25, 2026 13:00

Fix body type to represent all JSON value types

9c2d262

maennchen force-pushed the jm/hex_auth branch from c4c38cc to 9c2d262 Compare May 25, 2026 11:00

Add reauthentication

32a2bd1

maennchen marked this pull request as ready for review May 25, 2026 15:31

ericmj reviewed May 27, 2026

View reviewed changes

Allow Token Refresh Error with Repo Read & Optional

a6c7b2b

maennchen force-pushed the jm/hex_auth branch from edde7f7 to a6c7b2b Compare May 27, 2026 22:19

ericmj approved these changes Jun 2, 2026

View reviewed changes

wojtekmach approved these changes Jun 5, 2026

View reviewed changes

Conversation

maennchen commented Apr 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ericmj left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

maennchen commented Apr 14, 2026

Uh oh!

ericmj commented Apr 14, 2026

Uh oh!

maennchen commented Apr 14, 2026

Uh oh!

wojtekmach left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ericmj commented Apr 17, 2026

Uh oh!

maennchen commented Apr 20, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

wojtekmach left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

maennchen commented Apr 13, 2026 •

edited

Loading