barrel_mcp_client_auth behaviour (barrel_mcp v3.0.1)

View Source

Authorization behaviour for barrel_mcp_client.

The HTTP transport calls into this module to obtain the bearer token to attach to outgoing requests, and to refresh the token when the server returns 401.

A handle is an opaque term passed back into every callback. Static bearer tokens use barrel_mcp_client_auth_bearer; OAuth 2.1 with PKCE will use barrel_mcp_client_auth_oauth (Phase D).

Summary

Types

challenge/0
handle/0
t/0

Callbacks

challenge/2
header/1
init/1
refresh/2
request_headers/3
settled/1

Functions

challenge(_, Challenge)

Answer a server's refusal with a new handle. Runs the handle's challenge/2 when it has one, else its refresh/2 with the header. May take as long as a person takes to authorize; the transport calls it from a worker, never inline.

header(_)

Lookup the Authorization header for the current state.

new(_)

Construct an auth handle from a user-facing config term.

refresh(_, Www)

Refresh after a 401, returning a new handle.

request_headers(_, Method, Url)

Extra headers for one request, and the handle after issuing them.

settled(_)

Tell the handle a request was accepted.

Types

challenge/0

-type challenge() ::
          #{status := 401 | 403,
            www_authenticate := binary() | undefined,
            server_url := binary(),
            protocol_version := binary() | undefined,
            dpop_nonce => binary() | undefined}.

handle/0

-type handle() :: term().

t/0

-type t() :: {module(), handle()} | none.

Callbacks

challenge/2

(optional) 
-callback challenge(handle(), challenge()) -> {ok, handle()} | {error, term()}.
The transport reports a request the server accepted.

header/1

-callback header(handle()) -> {ok, binary()} | none | {error, term()}.

init/1

-callback init(Config :: term()) -> {ok, handle()} | {error, term()}.

refresh/2

-callback refresh(handle(), WwwAuthenticate :: binary() | undefined) -> {ok, handle()} | {error, term()}.

request_headers/3

(optional) 
-callback request_headers(handle(), Method :: binary(), Url :: binary()) ->
                             {[{binary(), binary()}], handle()}.

settled/1

(optional) 
-callback settled(handle()) -> handle().
Headers for one request beyond Authorization, such as a DPoP proof bound to this method and URL. The handle comes back because a proof changes state (jti, nonce).

Functions

challenge(_, Challenge)

-spec challenge(t(), challenge()) -> {ok, t()} | {error, term()}.

Answer a server's refusal with a new handle. Runs the handle's challenge/2 when it has one, else its refresh/2 with the header. May take as long as a person takes to authorize; the transport calls it from a worker, never inline.

header(_)

-spec header(t()) -> {ok, binary()} | none | {error, term()}.

Lookup the Authorization header for the current state.

new(_)

-spec new(none |
          {bearer, binary()} |
          {oauth, map()} |
          {oauth_client_credentials, map()} |
          {oauth_enterprise, map()} |
          {oauth_jwt_bearer, map()}) ->
             t() | {error, term()}.

Construct an auth handle from a user-facing config term.

refresh(_, Www)

-spec refresh(t(), binary() | undefined) -> {ok, t()} | {error, term()}.

Refresh after a 401, returning a new handle.

request_headers(_, Method, Url)

-spec request_headers(t(), binary(), binary()) -> {[{binary(), binary()}], t()}.

Extra headers for one request, and the handle after issuing them.

settled(_)

-spec settled(t()) -> t().

Tell the handle a request was accepted.