FastestMCP.Auth behaviour (fastest_mcp v0.3.0)

Copy Markdown View Source

Declarative auth wrapper and authenticator contract.

FastestMCP.Auth does two jobs:

  • it is the value attached to a server definition when you call FastestMCP.add_auth/3
  • it is the behaviour that concrete authenticators implement

Every authenticator is normalized behind the same contract so the rest of the runtime can stay transport-agnostic:

  • authenticate/3 verifies raw transport credentials and returns a normalized auth result

Runtime Shape

The runtime does not store provider-specific state directly on the context. Instead it stores a normalized %FastestMCP.Auth.Result{} with:

  • principal
  • auth
  • capabilities
  • audiences (verified resource audiences)
  • scopes (verified granted scopes)

That keeps the rest of the execution path independent from whether the source was a Phoenix assign, Plug middleware, static token, or application-owned authenticator.

Summary

Types

input()
t()

Callbacks

authenticate(input, t, map)

Functions

from_assign(assign, opts \\ [])

Builds an authenticator from one Plug/Phoenix assign.

new(provider_or_auth, opts \\ [])

Builds a new value for this module from the supplied options.

new_many(providers)

Builds multiple normalized values.

principal_fingerprint(principal)

Returns a stable fingerprint derived only from a verified principal.

resolve(auth, context, input)

Resolves the given input into the normalized runtime shape for this module.

result_from_context(context)

Extracts the auth result stored on the context.

www_authenticate(arg1, error, http_context)

Builds the WWW-Authenticate header value for an auth error.

Types

input()

@type input() :: map()

t()

@type t() :: %FastestMCP.Auth{options: map(), provider: module()}

Callbacks

authenticate(input, t, map)

@callback authenticate(input(), FastestMCP.Context.t(), map()) ::
  {:ok, FastestMCP.Auth.Result.t() | map()}
  | {:error, FastestMCP.Error.t() | atom() | {atom(), String.t()}}

Functions

from_assign(assign, opts \\ [])

Builds an authenticator from one Plug/Phoenix assign.

The HTTP transport can copy selected conn.assigns into auth input under "assigns". This helper turns one assign value into the normalized auth result used by the runtime.

new(provider_or_auth, opts \\ [])

Builds a new value for this module from the supplied options.

new_many(providers)

Builds multiple normalized values.

principal_fingerprint(principal)

Returns a stable fingerprint derived only from a verified principal.

resolve(auth, context, input)

Resolves the given input into the normalized runtime shape for this module.

result_from_context(context)

Extracts the auth result stored on the context.

www_authenticate(arg1, error, http_context)

Builds the WWW-Authenticate header value for an auth error.