@spec append_resource_metadata(String.t(), String.t()) :: String.t()

Append resource_metadata to a WWW-Authenticate challenge.

@spec authorization_server(
  Attesto.Config.t(),
  keyword()
) :: %{required(String.t()) => term()}

Build the authorization-server metadata document by delegating to Attesto.

@spec protected_resource(keyword()) :: %{required(String.t()) => term()}

Build an RFC 9728 protected-resource metadata document.

Required options:

• :resource - the protected resource identifier, usually the canonical MCP server URI such as "https://mcp.example.com/mcp".
• :authorization_servers - a non-empty list of issuer identifiers.

Common options include :scopes_supported, :bearer_methods_supported, :dpop_signing_alg_values_supported, and :tls_client_certificate_bound_access_tokens.

@spec protected_resource(Plug.Conn.t(), String.t(), keyword()) :: %{
  required(String.t()) => term()
}

Build protected-resource metadata from a Plug connection and resource path.

resource_path is the path of the MCP endpoint, for example "/mcp" or "/mcp/admin". The resource identifier is resolve_origin/2 (the resource server origin, pinned via :base_url/:origin) joined with that path. :authorization_servers defaults to the :config issuer (or an explicit :issuer string) when one is given - the trusted authorization server, advertised verbatim - and otherwise to the resource origin.

An explicit :resource or :authorization_servers opt overrides the derived value, and short-circuits its derivation: a pinned origin / issuer callback is not invoked (and cannot fail) for a value the host supplied outright.

@spec protected_resource_url(String.t(), String.t()) :: String.t()

@spec protected_resource_url(Plug.Conn.t(), String.t()) :: String.t()

Build the well-known metadata URL for an MCP resource path.

iex> AttestoMCP.Metadata.protected_resource_url("https://mcp.example.com", "/mcp")
"https://mcp.example.com/.well-known/oauth-protected-resource/mcp"

A Plug connection can also be passed as the first argument.

@spec protected_resource_url(Plug.Conn.t(), String.t(), keyword()) :: String.t()

Build the well-known metadata URL, resolving the origin via resolve_origin/2.

Pass :base_url/:origin in opts to pin the resource origin (so the challenge URL matches a pinned resource); with no such opt the live request origin is used.

@spec resolve_origin(
  Plug.Conn.t(),
  keyword()
) :: String.t()

Resolve the resource server origin used to build the resource identifier and the well-known metadata URL.

This is the protected resource's own origin (RFC 9728 resource), which is distinct from the authorization server (authorization_servers / the Attesto.Config issuer) - the two are often different hosts in a FAPI deployment, so the issuer is NOT used here. Precedence:

1. an explicit :base_url or :origin opt - a String.t(), a (Plug.Conn.t() -> String.t()) callback, or a {module, fun} / {module, fun, args} tuple (the conn is prepended to args), resolved at request time;
2. the live request origin (conn.scheme/conn.host/conn.port).

A blank or non-binary pin is treated as "not configured" and falls back to the request origin; a trailing slash is trimmed so the result joins cleanly with a resource path.

@spec resource_identifier(Plug.Conn.t(), String.t(), keyword()) :: String.t()

The canonical RFC 8707 / RFC 9728 resource identifier for this protected resource: the resolved origin joined with the resource path (for example "https://mcp.example.com/mcp").

This is the SINGLE source for the value that must agree across the chain — the RFC 9728 metadata resource field, the RFC 8707 resource a client requests, the aud the authorization server mints, and the audience the resource-server plug validates. Driving the audience check and the advertised metadata from this one function is what makes them consistent by construction (a host cannot configure them into disagreement). Origin precedence is resolve_origin/2's.

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

Build the WWW-Authenticate auth-param value for RFC 9728 metadata discovery.