@spec describe_token_error(atom()) :: {pos_integer(), String.t(), String.t()}

Translate a :reason atom returned from a core module into an {http_status, error_code, description} triple suitable for an OAuth error response.

@spec resource_metadata_url(module(), any()) :: String.t()

The URL of the protected-resource metadata document (RFC 9728) for this server — the value of the resource_metadata parameter in WWW-Authenticate challenges. PRM lives at the host root per RFC 9728, so path/query are stripped from the configured resource URL.

@spec send_bearer_error(Plug.Conn.t(), pos_integer(), String.t(), String.t() | nil) ::
  Plug.Conn.t()

Send a Bearer-auth error per RFC 6750 §3 — JSON body + a WWW-Authenticate: Bearer error="…", error_description="…" header.

Used for failures of Bearer-authenticated endpoints (e.g. RFC 7591 initial-access-token failures on /oauth/register).

Send a 400 with an RFC 7591 DCR-shaped error.

Codes: "invalid_redirect_uri", "invalid_client_metadata".

@spec send_insufficient_scope(
  Plug.Conn.t(),
  module(),
  [String.t()] | String.t(),
  keyword()
) ::
  Plug.Conn.t()

Send an RFC 6750 §3.1 insufficient_scope challenge — a 403 with a WWW-Authenticate header carrying the scopes the current operation needs and a pointer at the protected-resource metadata document, so MCP-style clients can drive a step-up authorization flow.

required_scopes should be all scopes the operation needs, in one challenge — challenging incrementally forces the client through one authorization round-trip per scope.

Options:

• :description — human-readable error_description
• :tenant — forwarded to the server's resource_url/1 resolution

@spec send_oauth_error(Plug.Conn.t(), pos_integer(), String.t(), String.t() | nil) ::
  Plug.Conn.t()

Send a JSON error per OAuth 2.0 / RFC 6749 §5.2.

Codes: "invalid_request", "invalid_client", "invalid_grant", "unsupported_grant_type", "invalid_scope", etc.