OzMcp.Auth.Challenge (OzMcp v0.9.0)

Copy Markdown View Source

A refusal of a request. It becomes an HTTP status and a WWW-Authenticate header value.

Summary

Functions

The key of the internal error table of the context for the challenge.

Turn the shortcut atoms that the authenticate/2 contract allows into a challenge and check a challenge: an unknown error, a description that is not a string or nil and scopes that are not a list of scope tokens are defects of the verifier. Any such value raises ArgumentError and the caller must answer a server error, never a pass.

Build the WWW-Authenticate value of the challenge.

The token is valid but misses scopes. HTTP 403. Raises ArgumentError when a scope does not match the RFC 6749 scope-token syntax, when the scopes are not a list, or when the description is neither a string nor nil.

The request is malformed. HTTP 400. Raises ArgumentError when the description is neither a string nor nil.

The bearer token is not valid. HTTP 401. Raises ArgumentError when the description is neither a string nor nil.

The request carries no usable bearer credential. HTTP 401 without an error parameter (RFC 6750, section 3.1).

Types

error()

@type error() :: nil | :invalid_token | :invalid_request | :insufficient_scope

t()

@type t() :: %OzMcp.Auth.Challenge{
  description: String.t() | nil,
  error: error(),
  scopes: [String.t()]
}

Functions

error_code(challenge)

@spec error_code(t()) ::
  :http_unauthorized | :http_bad_authorization | :http_insufficient_scope

The key of the internal error table of the context for the challenge.

from(challenge)

@spec from(t() | atom()) :: t()

Turn the shortcut atoms that the authenticate/2 contract allows into a challenge and check a challenge: an unknown error, a description that is not a string or nil and scopes that are not a list of scope tokens are defects of the verifier. Any such value raises ArgumentError and the caller must answer a server error, never a pass.

header(challenge, metadata_url, default_scopes \\ [])

@spec header(t(), String.t() | nil, [String.t()]) :: String.t()

Build the WWW-Authenticate value of the challenge.

metadata_url is the Protected Resource Metadata URL of the server. default_scopes are used when the challenge holds no scopes of its own. The description is cut to 200 characters. Each character that the header cannot hold becomes ?.

insufficient_scope(scopes, description \\ nil)

@spec insufficient_scope([String.t()], String.t() | nil) :: t()

The token is valid but misses scopes. HTTP 403. Raises ArgumentError when a scope does not match the RFC 6749 scope-token syntax, when the scopes are not a list, or when the description is neither a string nor nil.

invalid_request(description \\ nil)

@spec invalid_request(String.t() | nil) :: t()

The request is malformed. HTTP 400. Raises ArgumentError when the description is neither a string nor nil.

invalid_token(description \\ nil)

@spec invalid_token(String.t() | nil) :: t()

The bearer token is not valid. HTTP 401. Raises ArgumentError when the description is neither a string nor nil.

missing_token()

@spec missing_token() :: t()

The request carries no usable bearer credential. HTTP 401 without an error parameter (RFC 6750, section 3.1).