Secret Providers¶

async def check_config(
    self, config: dict[str, typing.Any], organization_id: str
) -> None:
    """Check a validated configuration against the provider.

    Called when a provider is created and when its configuration
    changes.

    Raises:
        InvalidConfiguration: The configuration is not safe to use.

    """

def check_key_host(self, host: str) -> str:
    """Return the normalized ``host`` of a provider key that this
    provider reads (``provider_key_usage.host``).

    Raises:
        ValueError: The host is not allowed, or the provider reads
            no provider keys (the default).

    """
    del host
    raise ValueError(f'The {self.type} provider reads no provider keys')

async def check_locator(
    self,
    config: dict[str, typing.Any],
    locator: dict[str, typing.Any],
    organization_id: str,
) -> None:
    """Check a validated locator against other bindings.

    Called when a binding is written, and for each binding of a
    provider when its configuration changes.

    Raises:
        InvalidConfiguration: The locator is not safe to use.

    """

def repository(
    self, config: dict[str, typing.Any], url: str
) -> tuple[str, str] | None:
    """Return ``(host, owner/name)`` of the repository at ``url``.

    For a provider that issues repository tokens: the agent runner
    clones the repository and asks the provider for a token on
    that host. ``None``: ``url`` is not a repository on the host of
    this configuration (the default).
    """
    del config, url
    return None

async def validate_binding(
    self,
    config: dict[str, typing.Any],
    locator: dict[str, typing.Any],
    organization_id: str,
    binding_id: uuid.UUID | None = None,
) -> dict[str, typing.Any]:
    """Return metadata of the bound secret, never its value."""
    raise BrokerError('operation_not_supported')

def validate_config(
    self, config: dict[str, typing.Any]
) -> dict[str, typing.Any]:
    """Return the normalized configuration.

    Raises:
        InvalidConfiguration: The configuration is not valid.

    """
    raise NotImplementedError

def validate_locator(
    self, locator: dict[str, typing.Any], credential_class: CredentialClass
) -> dict[str, typing.Any]:
    """Return the normalized binding locator. No provider call.

    Raises:
        InvalidConfiguration: The locator is not valid.

    """
    raise NotImplementedError

async def check_provider_key(
    self,
    organization_id: str,
    reference: str,
    *,
    host: str,
    app_id: str,
) -> object:
    """Check that a binding is a provider key for ``host`` and
    ``app_id``, without reading it.

    Raises:
        BrokerError: The binding is not such a provider key.

    """
    ...

def graph(self) -> graph.Graph:
    """Return the graph of imbi-api.

    Raises:
        BrokerError: ``secret_provider_unavailable`` when the graph
            is not open.

    """
    ...

async def provider_key(
    self,
    organization_id: str,
    reference: str,
    *,
    consumer: uuid.UUID | None,
    host: str,
    app_id: str,
    task_id: uuid.UUID | None = None,
) -> Material:
    """Return the material of a provider key for one consumer.

    A provider key is a binding that only imbi-api reads, for
    example the private key of a GitHub App. Its
    ``provider_key_usage`` names the ``host``, the ``app_id``, and
    the consumer bindings that may use it. No grant gives it to a
    task.

    Raises:
        BrokerError: The binding is not a provider key for this
            consumer, host, and App id, or its provider failed.

    """
    ...

async def vendor_token(
    self,
    organization_id: str,
    exchanger: identity.TokenExchanger,
    target: dict[str, typing.Any],
    *,
    agent_id: str,
) -> identity.AccessToken:
    """Mint a vendor access token for an agent (WIF plan 4.4).

    Core gets a new identity JWT from the organization's identity
    source and sets every claim. ``target`` must come from the
    binding of the agent, never from a request.

    Raises:
        BrokerError: Core or the vendor refused:
            ``secret_provider_unavailable`` when a retry can work,
            else ``secret_materialization_failed``. The reason is
            the :class:`identity.IdentityError` reason.

    """
    ...