PtcRunner.Kernel.MCPOAuth.Authority (PtcRunner v0.14.0)

Validated host authority for one OAuth-protected Streamable HTTP MCP server.

The struct is safe to pass only inside trusted host/runtime code. Its versioned fingerprint covers every default-expanded security field so any authority edit fences old grants. The struct itself is intentionally omitted from connector snapshots and public events.

Summary

Types

client()

registration()

t()

token_endpoint_auth_method()

Functions

cli_compatible?(authority)

Returns whether this authority can use the CLI loopback interaction.

from_host(value, endpoint, credential_names, opts \\ [])

Validates the host JSON OAuth block for one installed endpoint.

issuer(value, opts \\ [])

Validates and retains one exact HTTPS issuer identifier.

resource(value, opts \\ [])

Canonicalizes only scheme and host case for one HTTPS MCP resource.

Types

client()

@type client() :: %{
  :registration => registration(),
  :client_id => binary(),
  :token_endpoint_auth_method => token_endpoint_auth_method(),
  :grant_types => MapSet.t(binary()),
  :redirect =>
    {:loopback, %{host: binary(), path: binary()}} | {:https, [binary()]},
  optional(:client_secret_binding) => binary()
}

registration()

@type registration() :: :pre_registered | :client_id_metadata_document

t()

@type t() :: %PtcRunner.Kernel.MCPOAuth.Authority{
  additional_origins: [binary()],
  authorization_timeout_ms: pos_integer(),
  client: client(),
  default_scopes: PtcRunner.Kernel.MCPOAuth.Scope.scope_set(),
  fingerprint: binary(),
  installation_id: binary(),
  issuer: binary(),
  private_network_origins: [binary()],
  refresh_access: :none | :when_supported,
  resource: binary(),
  scope_ceiling: PtcRunner.Kernel.MCPOAuth.Scope.scope_set(),
  unknown_expiry_ttl_ms: pos_integer()
}

token_endpoint_auth_method()

@type token_endpoint_auth_method() :: :none | :client_secret_basic

Functions

cli_compatible?(authority)

@spec cli_compatible?(t()) :: boolean()

Returns whether this authority can use the CLI loopback interaction.

from_host(value, endpoint, credential_names, opts \\ [])

@spec from_host(map(), binary(), MapSet.t(binary()), keyword()) ::
  {:ok, t()} | {:error, :invalid_oauth_authority}

Validates the host JSON OAuth block for one installed endpoint.

credential_names is the complete host credential-name set. Only a confidential client's binding identifier is checked; its secret is not resolved.

issuer(value, opts \\ [])

@spec issuer(
  term(),
  keyword()
) :: {:ok, binary()} | {:error, :invalid_issuer}

Validates and retains one exact HTTPS issuer identifier.

Tests and trusted local embeddings may explicitly admit an HTTP literal-loopback issuer with allow_insecure_loopback: true; host configuration never enables that exception.

resource(value, opts \\ [])

@spec resource(
  term(),
  keyword()
) :: {:ok, binary()} | {:error, :invalid_resource}

Canonicalizes only scheme and host case for one HTTPS MCP resource.

Path bytes, explicit port spelling, trailing slash, and query bytes remain significant. Tests and trusted local embeddings may explicitly admit an HTTP literal-loopback resource with allow_insecure_loopback: true; host configuration never enables that exception.