X402.Extensions.AuthHints.Adapter (X402 v0.9.0)

X402.Extension adapter advertising the auth-hints extension.

plug X402.Plug.PaymentGate,
  routes: [...],
  extensions: [
    {X402.Extensions.AuthHints.Adapter,
     auth_requirements: [
       [accept_indexes: [1], methods: [X402.Extensions.AuthHints.oauth2(...)]]
     ]}
  ]

Every 402 response advertises X402.Extensions.AuthHints.extension/1 for the configured requirements, minus any index that falls outside the requirements actually offered to the request (a hook may have replaced them); a requirement left without indexes is not advertised, and neither is the extension when nothing remains. A context without requirements advertises the configuration unchanged.

The hints only announce what the route expects. Checking the credentials a client then presents is the application's job, in the handler or in a plug ahead of the gate.

Summary

Functions

advertise(opts, request_context)

Advertises the configured requirements, dropping indexes outside the request's requirements.

init(opts)

Validates the adapter options.

key()

Returns "auth-hints".

Functions

advertise(opts, request_context)

(since 0.9.0)

@spec advertise(
  keyword(),
  X402.Hooks.RequestContext.t()
) :: map() | nil

Advertises the configured requirements, dropping indexes outside the request's requirements.

Examples

iex> {:ok, opts} = X402.Extensions.AuthHints.Adapter.init(
...>   auth_requirements: [[accept_indexes: [0, 1], methods: [X402.Extensions.AuthHints.sign_in_with_x()]]]
...> )
iex> context = X402.Hooks.RequestContext.new(requirements: [%{"scheme" => "exact"}])
iex> X402.Extensions.AuthHints.Adapter.advertise(opts, context)["info"]
%{"authRequirements" => [%{"acceptIndexes" => [0], "methods" => [%{"type" => "sign-in-with-x"}]}]}

iex> {:ok, opts} = X402.Extensions.AuthHints.Adapter.init(
...>   auth_requirements: [[accept_indexes: [3], methods: [X402.Extensions.AuthHints.sign_in_with_x()]]]
...> )
iex> context = X402.Hooks.RequestContext.new(requirements: [%{"scheme" => "exact"}])
iex> X402.Extensions.AuthHints.Adapter.advertise(opts, context)
nil

init(opts)

(since 0.9.0)

@spec init(keyword()) :: {:ok, keyword()} | {:error, String.t()}

Validates the adapter options.

Options

:auth_requirements - Required. The requirements, as accepted by X402.Extensions.AuthHints.extension/1.

Examples

iex> requirements = [[accept_indexes: [1], methods: [X402.Extensions.AuthHints.sign_in_with_x()]]]
iex> {:ok, opts} = X402.Extensions.AuthHints.Adapter.init(auth_requirements: requirements)
iex> opts[:auth_requirements]["info"]["authRequirements"]
[%{"acceptIndexes" => [1], "methods" => [%{"type" => "sign-in-with-x"}]}]

iex> {:error, message} = X402.Extensions.AuthHints.Adapter.init(auth_requirements: [[accept_indexes: [], methods: []]])
iex> message =~ "accept indexes"
true

iex> {:error, message} = X402.Extensions.AuthHints.Adapter.init([])
iex> message =~ ":auth_requirements"
true

key()

(since 0.9.0)

@spec key() :: String.t()

Returns "auth-hints".

Examples

iex> X402.Extensions.AuthHints.Adapter.key()
"auth-hints"