@spec any_configured?(keyword() | MingaAgent.Credentials.Snapshot.t()) :: boolean()

Returns true if any local API-key or OAuth credential is configured.

This predicate never probes the network.

@spec dashboard_url_for(provider()) :: String.t() | nil

Returns the API key dashboard URL for a provider, or nil if unknown.

@spec env_var_for(provider()) :: String.t() | nil

Returns the environment variable name for a provider, or nil if unknown.

@spec known_providers() :: [provider()]

Returns the list of known provider names.

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

Returns the path to ~/.config/minga/oauth.json (XDG-aware).

@spec pin_oauth(:openai_codex, String.t()) ::
  {:ok, MingaAgent.ModelSelection.Credential.OAuth.t()} | {:error, term()}

Pins the exact OpenAI Codex account in Minga's explicit OAuth file.

ReqLLM owns refresh locking and persistence. Tokens returned while pinning are discarded; only the provider, provider key, account id, and exact path remain.

@spec request_options(MingaAgent.ModelSelection.credential_ref(), keyword()) ::
  {:ok, keyword()} | {:error, {:credential_unavailable, String.t()}}

Resolves one tagged credential reference for a single ReqLLM request.

API-key sources are exact. OAuth is refreshed by ReqLLM from Minga's explicit file and the returned provider, file, and account identities must match the pin before the access token is exposed to the caller.

@spec resolve(provider(), keyword()) :: {:ok, String.t(), key_source()} | :error

Resolves an API key for the given provider.

Checks the environment variable first, then the credentials file. Returns {:ok, key, source} if found, or :error if no key is configured anywhere.

@spec revoke(provider(), keyword()) :: :ok | {:error, term()}

Removes a stored API key for a provider.

Only removes from the credentials file. Environment variables are unaffected (and will still be used if set).

@spec snapshot(keyword()) :: MingaAgent.Credentials.Snapshot.t()

Acquires one secret-free local credential snapshot.

The credentials file is read once. Environment values retain precedence over stored values, and only their configured source is retained.

@spec status(keyword() | MingaAgent.Credentials.Snapshot.t()) :: [provider_status()]

Returns local authentication status for each hosted provider.

Each entry shows whether a key is configured and where it was found (:env, :file, :oauth, or nil). Keys themselves are never exposed.

@spec store(provider(), String.t(), keyword()) :: :ok | {:error, term()}

Stores an API key for a provider in the credentials file.

Creates the config directory and file if they don't exist. Sets file permissions to 0600 (owner read/write only).