@spec client_credentials_flow(map()) :: {:ok, token_response()} | {:error, term()}

Performs OAuth 2.1 client credentials flow.

This function implements the client credentials grant type for application-to-application authentication where no user interaction is required.

Parameters

Map containing:

• :client_id - OAuth client identifier
• :client_secret - Client secret
• :token_endpoint - Authorization server's token endpoint
• :scopes - List of requested scopes (optional)
• :resource - Optional resource indicator(s) (string or list of strings) per RFC 8707

Return Value

Returns {:ok, token_response} with access token information.

Example

{:ok, tokens} = ExMCP.Authorization.client_credentials_flow(%{
  client_id: "service-client",
  client_secret: "client-secret",
  token_endpoint: "https://auth.example.com/oauth/token",
  scopes: ["mcp:admin"],
  resource: "https://inventory.api.example.com"
})

access_token = tokens.access_token

@spec discover_server_metadata(String.t()) ::
  {:ok, server_metadata()} | {:error, term()}

Discovers server metadata from the authorization server.

This function implements RFC 8414 (OAuth 2.0 Authorization Server Metadata) to automatically discover authorization endpoints and capabilities.

Parameters

• issuer_url - Base URL of the authorization server

Return Value

Returns {:ok, server_metadata} with discovered endpoints and capabilities:

• :authorization_endpoint - Authorization endpoint URL
• :token_endpoint - Token endpoint URL
• :registration_endpoint - Dynamic registration endpoint (optional)
• :scopes_supported - Supported scopes
• :response_types_supported - Supported response types
• :grant_types_supported - Supported grant types
• :code_challenge_methods_supported - Supported PKCE methods

Example

{:ok, metadata} = ExMCP.Authorization.discover_server_metadata(
  "https://auth.example.com"
)

auth_endpoint = metadata.authorization_endpoint
token_endpoint = metadata.token_endpoint

@spec exchange_code_for_token(map()) :: {:ok, token_response()} | {:error, term()}

Exchanges an authorization code for an access token using PKCE.

This function completes the authorization code flow by exchanging the authorization code received from the callback for an access token.

Parameters

Map containing:

• :code - Authorization code from callback
• :code_verifier - PKCE code verifier from authorization state
• :client_id - OAuth client identifier
• :redirect_uri - Same redirect URI used in authorization request
• :token_endpoint - Authorization server's token endpoint
• :client_secret - Client secret (optional, for confidential clients)
• :resource - Optional resource indicator(s) (string or list of strings) per RFC 8707

Return Value

Returns {:ok, token_response} with:

• :access_token - Bearer token for API requests
• :token_type - Usually "Bearer"
• :expires_in - Token lifetime in seconds (optional)
• :refresh_token - Token for refreshing access (optional)
• :scope - Granted scopes (optional)

Example

{:ok, tokens} = ExMCP.Authorization.exchange_code_for_token(%{
  code: "auth_code_from_callback",
  code_verifier: state.code_verifier,
  client_id: "my-mcp-client",
  redirect_uri: "http://localhost:8080/callback",
  token_endpoint: "https://auth.example.com/oauth/token",
  resource: "https://mcp.example.com"
})

access_token = tokens.access_token

@spec generate_pkce_challenge() :: {:ok, String.t(), String.t()} | {:error, term()}

Generates PKCE code challenge parameters.

This function generates the PKCE (Proof Key for Code Exchange) parameters required for secure authorization code flows.

Return Value

Returns {:ok, code_verifier, code_challenge} where:

• code_verifier - Random string stored securely by client
• code_challenge - SHA256 hash of code_verifier for authorization request

Example

{:ok, verifier, challenge} = ExMCP.Authorization.generate_pkce_challenge()

# Use challenge in authorization URL
# Store verifier securely for token exchange

@spec start_authorization_flow(authorization_config()) ::
  {:ok, String.t(), map()} | {:error, term()}

Starts an OAuth 2.1 authorization code flow with PKCE.

This function initiates the authorization code flow for user-based authentication. It generates secure PKCE parameters and returns the authorization URL that the user should visit to grant consent.

Parameters

• config - Authorization configuration map containing:
  • :client_id - OAuth client identifier
  • :redirect_uri - Callback URI after authorization
  • :authorization_endpoint - Authorization server's authorize endpoint
  • :scopes - List of requested scopes
  • :resource - Optional resource indicator(s) (string or list of strings) per RFC 8707
  • :additional_params - Optional additional query parameters

Return Value

Returns {:ok, authorization_url, state} where:

• authorization_url - URL for user to visit and authorize
• state - Map containing code_verifier and state parameter (store securely)

Security

• All endpoints must use HTTPS (except localhost for development)
• PKCE code verifier is generated securely and must be stored
• State parameter prevents CSRF attacks

Example

{:ok, auth_url, state} = ExMCP.Authorization.start_authorization_flow(%{
  client_id: "my-mcp-client",
  redirect_uri: "http://localhost:8080/callback",
  authorization_endpoint: "https://auth.example.com/oauth/authorize",
  scopes: ["mcp:read", "mcp:write"],
  resource: "https://mcp.example.com"
})

# Store state securely (contains code_verifier)
# Redirect user to auth_url

@spec token_request(map()) :: {:ok, map()} | {:error, any()}

Makes a token request to the authorization server.

Used internally by TokenManager for refresh operations.

@spec validate_token(String.t(), String.t()) :: {:ok, map()} | {:error, term()}

Validates an access token with the authorization server.

This function uses OAuth 2.0 token introspection to validate whether an access token is still active and get information about it.

Parameters

• token - Access token to validate
• introspection_endpoint - Token introspection endpoint URL

Return Value

Returns {:ok, introspection_response} if token is active, or {:error, :token_inactive} if token is inactive.

Example

case ExMCP.Authorization.validate_token(token, introspection_endpoint) do
  {:ok, info} ->
    # Token is valid, info contains claims
    :ok
  {:error, :token_inactive} ->
    # Token expired or revoked
    :error
end

@spec verify_pkce_challenge(String.t(), String.t()) :: :ok | {:error, term()}

Verifies a PKCE code challenge.

This function verifies that a code verifier matches the expected code challenge. Used by authorization servers to validate PKCE flows.

Parameters

• code_verifier - The code verifier from token exchange
• expected_challenge - The code challenge from authorization request

Return Value

Returns :ok if verification succeeds, {:error, reason} otherwise.

Example

case ExMCP.Authorization.verify_pkce_challenge(verifier, challenge) do
  :ok -> # Valid
  {:error, _reason} -> # Invalid
end