yera 0.11.1

yera.tools.mcp.oauth_profiles

Predefined OAuth client behavior for MCP providers.

Symbols

def compose_github_mcp_scopes — Compose GitHub OAuth scopes from an explicit access selection.
def default_github_mcp_access_level — Return Yera's least-privilege GitHub MCP recommendation.
def get_mcp_oauth_client_profile — Return a predefined MCP OAuth client profile.
def github_mcp_access_levels — Return the ordered GitHub MCP repository-access choices.
def github_mcp_optional_permissions — Return the optional GitHub MCP account permissions.
class GitHubMCPAccessLevel — Describe one selectable GitHub MCP repository-access mode.
class GitHubMCPOptionalPermission — Describe one optional GitHub MCP account permission.
class MCPOAuthClientProfile — Describe how Yera authenticates with one MCP provider.
def resolve_mcp_oauth_client_profile — Resolve the predefined profile referenced by OAuth configuration.
def yera_oauth_client_metadata_document — Return Yera's canonical public OAuth client metadata document.

compose_github_mcp_scopes

compose_github_mcp_scopes(
    access_level: GitHubMCPAccessLevel,
    selected_permissions: tuple[str, ...],
) → tuple[str, ...]

Compose GitHub OAuth scopes from an explicit access selection.

Parameters

access_level
type: GitHubMCPAccessLevel

Selected repository-access policy.

selected_permissions
type: tuple[str, ...]

Stable names of optional account permissions.

Returns

type: tuple[str, ...]

Requested scopes in deterministic policy order without duplicates.

Raises

ValueError

If an optional permission name is unknown.

default_github_mcp_access_level

default_github_mcp_access_level() → GitHubMCPAccessLevel

Return Yera's least-privilege GitHub MCP recommendation.

Returns

type: GitHubMCPAccessLevel

Public-repository read-only access with no additional OAuth scopes.

get_mcp_oauth_client_profile

get_mcp_oauth_client_profile(
    name: str,
) → MCPOAuthClientProfile | None

Return a predefined MCP OAuth client profile.

Parameters

name
type: str

Stable profile name from MCP server configuration.

Returns

type: MCPOAuthClientProfile | None

The matching client profile, or None when it is unknown.

github_mcp_access_levels

github_mcp_access_levels() → tuple[GitHubMCPAccessLevel, ...]

Return the ordered GitHub MCP repository-access choices.

Returns

type: tuple[GitHubMCPAccessLevel, ...]

Immutable access levels ordered from least to most privileged.

github_mcp_optional_permissions

github_mcp_optional_permissions() → tuple[GitHubMCPOptionalPermission, ...]

Return the optional GitHub MCP account permissions.

Returns

type: tuple[GitHubMCPOptionalPermission, ...]

Immutable permissions ordered for presentation and scope composition.

GitHubMCPAccessLevel

Inherits: BaseModel

Describe one selectable GitHub MCP repository-access mode.

Fields

name
type: str (required)

Stable identifier used by configuration and OAuth profiles.

title
type: str (required)

Concise user-facing choice label.

description
type: str (required)

Explanation of repository reach and available MCP tools.

url
type: str (required)

GitHub remote MCP endpoint enforcing the selected tool mode.

base_scopes
type: tuple[str, ...] = ()

OAuth scopes inherently required by this repository mode.

least_privilege
type: bool = False

Whether this is Yera's recommended minimum grant.

warning
type: str | None = None

Important consequence requiring additional user attention.

GitHubMCPOptionalPermission

Inherits: BaseModel

Describe one optional GitHub MCP account permission.

Fields

name
type: str (required)

Stable identifier submitted by the setup form.

title
type: str (required)

Concise user-facing choice label.

description
type: str (required)

Explanation of the additional account data exposed.

scope
type: str (required)

Exact GitHub OAuth scope requested when enabled.

default_enabled
type: bool = False

Whether setup selects this permission initially.

MCPOAuthClientProfile

Inherits: BaseModel

Describe how Yera authenticates with one MCP provider.

Fields

name
type: str (required)

Stable name persisted in MCP server configuration.

client_kind
type: Literal['public', 'confidential'] (required)

Whether the OAuth client can protect a client secret.

grant_type
type: Literal['authorization_code', 'device_code'] (required)

OAuth grant used to authorize the user.

registration_method
type: Literal['cimd', 'dcr', 'pre_registered'] (required)

How the provider recognizes Yera as a client.

callback_strategy
type: Literal['none', 'ephemeral_loopback', 'fixed_loopback', 'hosted'] (required)

How authorization results return to Yera.

availability
type: Literal['open', 'vendor_approval', 'internal_only'] (required)

Whether users may connect without provider approval.

supports_static_token
type: bool = False

Whether users may supply a token instead.

client_id
type: str | None = None

Optional public identifier assigned to Yera by the provider.

client_metadata_url
type: str | None = None

Optional HTTPS Client ID Metadata Document URL.

device_authorization_endpoint
type: str | None = None

Optional endpoint issuing device codes.

token_endpoint
type: str | None = None

Optional endpoint issuing OAuth tokens.

default_scopes
type: tuple[str, ...] = ()

Provider-specific scopes requested by default.

Methods

require_client_id — Return the profile's deployed OAuth client identifier.

MCPOAuthClientProfile.require_client_id

require_client_id() → str

Return the profile's deployed OAuth client identifier.

Returns

type: str

Public OAuth client identifier configured for this Yera build.

Raises

MCPAuthenticationError

If the client has not been registered.

resolve_mcp_oauth_client_profile

resolve_mcp_oauth_client_profile(
    auth: MCPOAuthAuth,
) → MCPOAuthClientProfile | None

Resolve the predefined profile referenced by OAuth configuration.

Parameters

auth
type: MCPOAuthAuth

Persisted OAuth authentication configuration.

Returns

type: MCPOAuthClientProfile | None

The selected predefined profile, or None for generic OAuth.

Raises

MCPAuthenticationError

If an explicitly selected profile is unknown.

yera_oauth_client_metadata_document

yera_oauth_client_metadata_document() → dict[str, object]

Return Yera's canonical public OAuth client metadata document.

Returns

type: dict[str, object]

JSON-compatible CIMD metadata to publish at Yera's client ID URL.