induscode 0.1.0__py3-none-any.whl

induscode/launch/credentials.py

@@ -0,0 +1,852 @@
+"""Credential command — :func:`run_credential_command`.
+
+The top-level ``signin`` / ``signout`` surface. Sign-in supports two methods:
+a browser sign-in (OAuth) for the providers the adapter registry exposes, and
+an api-key flow for every provider in the directory. When a provider is
+sign-in-capable the command prefers the browser flow but still lets the user
+pick an api key; for the rest it stores a key directly. The env-var override
+is consulted first via the framework :func:`indusagi.ai.get_env_api_key`, so a
+user who already exported (e.g.) ``ANTHROPIC_API_KEY`` can sign in without
+re-typing the secret.
+
+The command owns the first positional token only: it returns
+``handled=False`` when that token is neither
+:data:`~.contract.CredentialVerb` so the caller falls through to a normal
+launch. Every failure is a typed :class:`~.contract.CredentialFault`; nothing
+is signalled by a string sentinel or a bare ``sys.exit``.
+
+I/O is injected. The default :class:`CredentialIo` wraps stdout plus
+:func:`input` / :func:`getpass.getpass`, but tests drive the whole flow over
+an in-memory stand-in with no real terminal and an in-memory vault.
+
+(Port of TS ``src/launch/credentials.ts``; the browser path runs over the
+launch OAuth adapter rather than the TS framework provider registry.)
+"""
+
+from __future__ import annotations
+
+import asyncio
+import getpass
+import re
+import sys
+from collections.abc import Awaitable, Sequence
+from dataclasses import dataclass
+from typing import Final, Literal, Protocol, TypeAlias
+
+from indusagi.ai import get_env_api_key
+
+from .contract import (
+    AuthVault,
+    CredentialFault,
+    CredentialFaultKind,
+    CredentialVerb,
+    ProviderEntry,
+    credential_fault,
+)
+from .oauth import (
+    OAuthAuthorization,
+    OAuthLoginCallbacks,
+    OAuthPrompt,
+    get_oauth_provider,
+    list_login_providers,
+    open_login_url,
+    start_oauth_login,
+)
+
+__all__ = [
+    "CredentialIo",
+    "CredentialResult",
+    "PROVIDER_DIRECTORY",
+    "SigninMethod",
+    "as_signin_method",
+    "default_credential_io",
+    "find_provider",
+    "format_credential_fault",
+    "is_oauth_capable",
+    "run_credential_command",
+    "validate_account_name",
+    "validate_api_key",
+]
+
+
+# ---------------------------------------------------------------------------
+# Injected I/O
+# ---------------------------------------------------------------------------
+
+
+class CredentialIo(Protocol):
+    """The console seam the credential command reads and writes through.
+
+    Pinned to the three operations the flow actually needs — emit a line, read
+    a line of input, and read a secret line — so a test can capture output
+    into a list and feed scripted answers without a real TTY.
+    """
+
+    def print(self, line: str) -> None:
+        """Emit one line of human-facing text."""
+        ...
+
+    async def ask(self, prompt: str) -> str:
+        """Prompt for and read one line of visible input."""
+        ...
+
+    async def ask_secret(self, prompt: str) -> str:
+        """Prompt for and read one line of secret input (key entry)."""
+        ...
+
+
+class _DefaultCredentialIo:
+    """The default :class:`CredentialIo` backed by stdout, :func:`input`, and
+    :func:`getpass.getpass` (which mutes the echo while the secret is
+    typed)."""
+
+    def print(self, line: str) -> None:
+        sys.stdout.write(line if line.endswith("\n") else line + "\n")
+
+    async def ask(self, prompt: str) -> str:
+        answer = await asyncio.to_thread(input, prompt)
+        return answer.strip()
+
+    async def ask_secret(self, prompt: str) -> str:
+        answer = await asyncio.to_thread(getpass.getpass, prompt)
+        return answer.strip()
+
+
+def default_credential_io() -> CredentialIo:
+    """Build the live terminal-backed :class:`CredentialIo`."""
+    return _DefaultCredentialIo()
+
+
+# ---------------------------------------------------------------------------
+# Provider directory
+# ---------------------------------------------------------------------------
+
+#: The api-key provider directory: every provider the sign-in surface can
+#: store a key for, with its conventional env var and the page a user obtains
+#: a key from. These are external provider facts; ``env_key`` is the variable
+#: :func:`indusagi.ai.get_env_api_key` reads for the env-first shortcut.
+PROVIDER_DIRECTORY: Final[tuple[ProviderEntry, ...]] = (
+    ProviderEntry(
+        id="anthropic",
+        label="Anthropic (Claude)",
+        env_key="ANTHROPIC_API_KEY",
+        docs_url="https://console.anthropic.com/settings/keys",
+    ),
+    ProviderEntry(
+        id="openai",
+        label="OpenAI",
+        env_key="OPENAI_API_KEY",
+        docs_url="https://platform.openai.com/api-keys",
+    ),
+    ProviderEntry(
+        id="google",
+        label="Google Gemini",
+        env_key="GEMINI_API_KEY",
+        docs_url="https://aistudio.google.com/apikey",
+    ),
+    ProviderEntry(
+        id="xai",
+        label="xAI (Grok)",
+        env_key="XAI_API_KEY",
+        docs_url="https://console.x.ai",
+    ),
+    ProviderEntry(
+        id="groq",
+        label="Groq",
+        env_key="GROQ_API_KEY",
+        docs_url="https://console.groq.com/keys",
+    ),
+    ProviderEntry(
+        id="cerebras",
+        label="Cerebras",
+        env_key="CEREBRAS_API_KEY",
+        docs_url="https://cloud.cerebras.ai",
+    ),
+    ProviderEntry(
+        id="mistral",
+        label="Mistral",
+        env_key="MISTRAL_API_KEY",
+        docs_url="https://console.mistral.ai/api-keys",
+    ),
+    ProviderEntry(
+        id="openrouter",
+        label="OpenRouter",
+        env_key="OPENROUTER_API_KEY",
+        docs_url="https://openrouter.ai/keys",
+    ),
+    ProviderEntry(
+        id="minimax",
+        label="MiniMax",
+        env_key="MINIMAX_API_KEY",
+        docs_url="https://www.minimax.io",
+    ),
+    ProviderEntry(
+        id="kimi",
+        label="Kimi (Moonshot)",
+        env_key="MOONSHOT_API_KEY",
+        docs_url="https://platform.moonshot.ai/console/api-keys",
+    ),
+    ProviderEntry(
+        id="sarvam",
+        label="Sarvam",
+        env_key="SARVAM_API_KEY",
+        docs_url="https://dashboard.sarvam.ai",
+    ),
+    ProviderEntry(
+        id="krutrim",
+        label="Krutrim",
+        env_key="KRUTRIM_API_KEY",
+        docs_url="https://cloud.olakrutrim.com",
+    ),
+    ProviderEntry(
+        id="nvidia",
+        label="NVIDIA",
+        env_key="NVIDIA_API_KEY",
+        docs_url="https://build.nvidia.com",
+    ),
+    ProviderEntry(
+        id="zai",
+        label="Z.ai",
+        env_key="ZAI_API_KEY",
+        docs_url="https://z.ai",
+    ),
+)
+
+
+def find_provider(id: str) -> ProviderEntry | None:
+    """Look up a provider entry by id (case-insensitive over the directory)."""
+    needle = id.strip().lower()
+    for entry in PROVIDER_DIRECTORY:
+        if entry.id.lower() == needle:
+            return entry
+    return None
+
+
+# ---------------------------------------------------------------------------
+# Sign-in method
+# ---------------------------------------------------------------------------
+
+#: The two ways a provider can be signed in to.
+#:
+#: - ``oauth``   — a browser sign-in driven by the adapter registry.
+#: - ``api-key`` — paste / store a provider api key.
+SigninMethod: TypeAlias = Literal["oauth", "api-key"]
+
+
+def as_signin_method(value: str | None) -> SigninMethod | None:
+    """Narrow a ``--method`` value to a :data:`SigninMethod`."""
+    normalised = value.strip().lower() if value is not None else None
+    if normalised == "oauth":
+        return "oauth"
+    if normalised == "api-key" or normalised == "apikey":
+        return "api-key"
+    return None
+
+
+def is_oauth_capable(id: str) -> bool:
+    """Whether a provider id can be signed in to through the browser
+    registry."""
+    return get_oauth_provider(id) is not None
+
+
+# ---------------------------------------------------------------------------
+# Validation
+# ---------------------------------------------------------------------------
+
+#: Lower bound on a plausible api key length.
+_MIN_KEY_LENGTH: Final[int] = 20
+#: Upper bound on an account name.
+_MAX_ACCOUNT_LENGTH: Final[int] = 50
+#: Allowed characters in an account name.
+_ACCOUNT_PATTERN: Final[re.Pattern[str]] = re.compile(r"^[A-Za-z0-9_-]+$")
+#: Substrings that mark a placeholder rather than a real key.
+_PLACEHOLDER_MARKERS: Final[tuple[str, ...]] = (
+    "your-api-key",
+    "your_api_key",
+    "xxxx",
+    "placeholder",
+    "changeme",
+    "<",
+)
+
+
+def validate_api_key(key: str) -> CredentialFault | None:
+    """Validate an api key against the format rules: non-empty, at least
+    :data:`_MIN_KEY_LENGTH` characters, and free of placeholder markers.
+    Returns a typed :class:`~.contract.CredentialFault` on rejection, or
+    ``None`` when the key passes."""
+    trimmed = key.strip()
+    if len(trimmed) == 0:
+        return credential_fault(
+            "invalid-key",
+            "No api key was provided.",
+            hint="Paste the key from the provider dashboard and try again.",
+        )
+    if len(trimmed) < _MIN_KEY_LENGTH:
+        return credential_fault(
+            "invalid-key",
+            f"The api key is too short (expected at least {_MIN_KEY_LENGTH} characters).",
+            hint="Copy the full key, including any prefix.",
+        )
+    lowered = trimmed.lower()
+    if any(marker in lowered for marker in _PLACEHOLDER_MARKERS):
+        return credential_fault(
+            "invalid-key",
+            "The value looks like a placeholder rather than a real api key.",
+            hint="Replace the placeholder with the actual key.",
+        )
+    return None
+
+
+def validate_account_name(name: str) -> CredentialFault | None:
+    """Validate an account name: at most :data:`_MAX_ACCOUNT_LENGTH`
+    characters and matching :data:`_ACCOUNT_PATTERN`. Returns a typed fault on
+    rejection, or ``None`` when the name is acceptable."""
+    trimmed = name.strip()
+    if len(trimmed) == 0:
+        return credential_fault(
+            "invalid-account",
+            "The account name is empty.",
+            hint="Use letters, digits, dashes, or underscores.",
+        )
+    if len(trimmed) > _MAX_ACCOUNT_LENGTH:
+        return credential_fault(
+            "invalid-account",
+            f"The account name is too long (max {_MAX_ACCOUNT_LENGTH} characters).",
+        )
+    if _ACCOUNT_PATTERN.match(trimmed) is None:
+        return credential_fault(
+            "invalid-account",
+            "The account name contains unsupported characters.",
+            hint="Use letters, digits, dashes, or underscores only.",
+        )
+    return None
+
+
+# ---------------------------------------------------------------------------
+# Command surface
+# ---------------------------------------------------------------------------
+
+#: The default account name used when the user does not name one explicitly.
+_DEFAULT_ACCOUNT: Final[str] = "default"
+
+
+@dataclass(frozen=True, slots=True)
+class CredentialResult:
+    """The outcome of :func:`run_credential_command`.
+
+    :attr:`handled` reports whether the first positional token was a
+    recognised :data:`~.contract.CredentialVerb`; when ``False``, the caller
+    proceeds to a normal launch unchanged. :attr:`fault` carries a typed
+    failure when the command was handled but did not complete."""
+
+    # Whether this invocation was a signin / signout command.
+    handled: bool
+    # The verb that ran, when handled is True.
+    verb: CredentialVerb | None = None
+    # The provider id the verb acted on, when one was resolved.
+    provider: str | None = None
+    # A typed failure, present only when the handled command did not complete.
+    fault: CredentialFault | None = None
+
+
+def _as_verb(token: str | None) -> CredentialVerb | None:
+    """Narrow the leading token to a :data:`~.contract.CredentialVerb`.
+
+    ``login`` / ``logout`` are accepted as the natural-language aliases of
+    ``signin`` / ``signout``, so ``pindus login`` does the obvious thing
+    rather than being mistaken for a chat prompt."""
+    if token == "signin" or token == "login":
+        return "signin"
+    if token == "signout" or token == "logout":
+        return "signout"
+    return None
+
+
+class _FaultSignal(Exception):
+    """Internal control-flow carrier for a fault raised mid-resolution (TS
+    threw the plain fault object; Python needs an Exception)."""
+
+    def __init__(self, fault: CredentialFault) -> None:
+        super().__init__(fault.message)
+        self.fault = fault
+
+
+def _to_vault_fault(cause: object) -> CredentialFault:
+    """Wrap an unexpected thrown error as a ``vault``
+    :class:`~.contract.CredentialFault`.
+
+    # parity: the TS flow threw *plain fault objects* (not Errors) from the
+    # provider resolvers; ``cause instanceof Error`` was false for them, so
+    # they degraded to this generic vault message. The port preserves that
+    # quirk by treating the internal fault signal like a non-Error.
+    """
+    if isinstance(cause, Exception) and not isinstance(cause, _FaultSignal):
+        message = str(cause)
+    else:
+        message = "The credential store failed."
+    return credential_fault("vault", message, cause=cause)
+
+
+async def run_credential_command(
+    argv: Sequence[str],
+    *,
+    vault: AuthVault,
+    profile_dir: str,
+    io: CredentialIo | None = None,
+) -> CredentialResult:
+    """Run the sign-in / sign-out command.
+
+    Returns ``handled=False`` immediately when ``argv[0]`` is neither verb, so
+    the orchestrator can call this first and fall through on a miss. Otherwise
+    it resolves the provider (prompting from the directory when none is
+    named), runs the verb, and resolves a :class:`CredentialResult` — never
+    raising for an expected failure, which surfaces as the result's ``fault``.
+
+    :param argv: the raw token list following the program name
+    :param vault: the injected credential store
+    :param profile_dir: absolute directory the vault persists credentials
+        under (informational; the vault owns the writes)
+    :param io: the console seam; defaults to the live terminal
+    """
+    del profile_dir  # informational in the TS contract too; the vault writes
+    verb = _as_verb(argv[0] if len(argv) > 0 else None)
+    if verb is None:
+        return CredentialResult(handled=False)
+
+    live_io = io if io is not None else default_credential_io()
+    rest = list(argv[1:])
+    named_provider, account, method, list_flag = _read_verb_flags(rest)
+
+    # `--list` short-circuits the sign-in verb: it reports every saved account
+    # without prompting and stores nothing. It is meaningless for sign-out,
+    # where the verb already names what to remove, so it is honoured on
+    # `signin` only.
+    if verb == "signin" and list_flag:
+        try:
+            await _do_list_accounts(vault, live_io)
+            return CredentialResult(handled=True, verb=verb)
+        except Exception as cause:
+            return CredentialResult(handled=True, verb=verb, fault=_to_vault_fault(cause))
+
+    try:
+        if verb == "signin":
+            resolved = await _resolve_signin_target(named_provider, live_io)
+            if resolved is None:
+                return CredentialResult(
+                    handled=True,
+                    verb=verb,
+                    fault=credential_fault("aborted", "No provider was selected."),
+                )
+
+            fault = await _do_signin(resolved, account, method, vault, live_io)
+            return CredentialResult(
+                handled=True, verb=verb, provider=resolved.id, fault=fault
+            )
+
+        provider = await _resolve_provider(named_provider, live_io)
+        if provider is None:
+            return CredentialResult(
+                handled=True,
+                verb=verb,
+                fault=credential_fault("aborted", "No provider was selected."),
+            )
+
+        fault = await _do_signout(provider, account, vault, live_io)
+        return CredentialResult(
+            handled=True, verb=verb, provider=provider.id, fault=fault
+        )
+    except Exception as cause:
+        return CredentialResult(handled=True, verb=verb, fault=_to_vault_fault(cause))
+
+
+def _read_verb_flags(
+    rest: Sequence[str],
+) -> tuple[str | None, str | None, SigninMethod | None, bool]:
+    """Extract the optional ``--provider`` / ``--account`` / ``--method`` /
+    ``--list`` flags (and the bare positional fallbacks) from the verb tail.
+    The first positional is treated as the provider when no ``--provider``
+    flag is present. ``--oauth`` / ``--api-key`` are accepted as shorthands
+    for the corresponding ``--method`` value; ``--list`` is a bare switch that
+    requests a read-only listing of saved accounts."""
+    provider: str | None = None
+    account: str | None = None
+    method: SigninMethod | None = None
+    list_flag = False
+    positionals: list[str] = []
+    i = 0
+    while i < len(rest):
+        token = rest[i]
+        if token == "--provider" and i + 1 < len(rest):
+            i += 1
+            provider = rest[i]
+        elif token == "--account" and i + 1 < len(rest):
+            i += 1
+            account = rest[i]
+        elif token == "--method" and i + 1 < len(rest):
+            i += 1
+            method = as_signin_method(rest[i])
+        elif token == "--oauth":
+            method = "oauth"
+        elif token == "--api-key" or token == "--apikey":
+            method = "api-key"
+        elif token == "--list" or token == "--ls":
+            list_flag = True
+        elif not token.startswith("-"):
+            positionals.append(token)
+        i += 1
+    if provider is None and positionals:
+        provider = positionals[0]
+    return provider, account, method, list_flag
+
+
+async def _do_list_accounts(vault: AuthVault, io: CredentialIo) -> None:
+    """Print every saved provider account, grouped by provider, without
+    prompting.
+
+    Walks the merged sign-in directory for the full set of provider ids the
+    app knows (deduplicated, since a provider can appear under both the
+    browser and api-key directories), queries the vault for each, and prints
+    one line per saved account — tagging the provider default and the stored
+    credential kind. When no provider holds a saved account it prints a single
+    "none" line. Read-only: it never writes to the vault."""
+    seen: set[str] = set()
+    providers: list[tuple[str, str]] = []
+    for entry in list_login_providers():
+        if entry.id in seen:
+            continue
+        seen.add(entry.id)
+        providers.append((entry.id, entry.label))
+
+    io.print("Saved accounts:")
+    any_found = False
+    for provider_id, label in providers:
+        accounts = await vault.list_accounts(provider_id)
+        if not accounts:
+            continue
+        any_found = True
+        fallback_default = await vault.default_account(provider_id)
+        io.print(f"  {label} ({provider_id}):")
+        for account in accounts:
+            kind = await vault.auth_kind(provider_id, account)
+            marker = " (default)" if account == fallback_default else ""
+            kind_label = (
+                "browser" if kind == "oauth" else "api key" if kind == "apiKey" else "unknown"
+            )
+            io.print(f"    - {account}{marker} [{kind_label}]")
+    if not any_found:
+        io.print("  (none)")
+
+
+async def _resolve_provider(
+    named: str | None, io: CredentialIo
+) -> ProviderEntry | None:
+    """Resolve the provider to act on. When a name was supplied it is
+    validated against the directory; when none was, the directory is printed
+    and the user picks by number. Returns ``None`` only when the interactive
+    pick is aborted; raises a typed fault for a named-but-unknown provider."""
+    if named is not None:
+        entry = find_provider(named)
+        if entry is None:
+            raise _FaultSignal(
+                credential_fault(
+                    "unknown-provider",
+                    f"Unknown provider: {named}.",
+                    hint="Run the command with no provider to list the choices.",
+                )
+            )
+        return entry
+
+    io.print("Available providers:")
+    for index, entry in enumerate(PROVIDER_DIRECTORY):
+        io.print(f"  {index + 1}. {entry.label} ({entry.env_key})")
+    answer = await io.ask("Select a provider by number: ")
+    if len(answer) == 0:
+        return None
+    index = _parse_pick(answer)
+    if index is None or index < 0 or index >= len(PROVIDER_DIRECTORY):
+        raise _FaultSignal(
+            credential_fault(
+                "unknown-provider", "That is not one of the listed providers."
+            )
+        )
+    return PROVIDER_DIRECTORY[index]
+
+
+def _parse_pick(answer: str) -> int | None:
+    """Parse a 1-based menu answer into a 0-based index (None on a
+    non-integer)."""
+    try:
+        return int(answer.strip(), 10) - 1
+    except ValueError:
+        return None
+
+
+@dataclass(frozen=True, slots=True)
+class _SigninTarget:
+    """A resolved sign-in target — the provider id and label the sign-in flow
+    acts on, plus whether a browser sign-in is available for it. An
+    api-key-only provider carries its directory :class:`ProviderEntry`; a
+    browser-sign-in provider that has no api-key directory entry has none."""
+
+    # Stable provider id.
+    id: str
+    # Human-facing label.
+    label: str
+    # Whether the adapter registry can sign this provider in via the browser.
+    oauth_capable: bool
+    # The api-key directory entry, when one exists for this provider.
+    api_key_entry: ProviderEntry | None = None
+
+
+def _make_signin_target(id: str) -> _SigninTarget | None:
+    """Build a :class:`_SigninTarget` for a provider id (looked up across both
+    kinds)."""
+    api_key_entry = find_provider(id)
+    oauth_capable = is_oauth_capable(id)
+    if api_key_entry is None and not oauth_capable:
+        return None
+    merged = next((p for p in list_login_providers() if p.id == id), None)
+    label = (
+        api_key_entry.label
+        if api_key_entry is not None
+        else merged.label if merged is not None else id
+    )
+    return _SigninTarget(
+        id=id, label=label, oauth_capable=oauth_capable, api_key_entry=api_key_entry
+    )
+
+
+async def _resolve_signin_target(
+    named: str | None, io: CredentialIo
+) -> _SigninTarget | None:
+    """Resolve the sign-in target. When a name was supplied it is validated
+    across both the browser-sign-in registry and the api-key directory; when
+    none was, the merged directory is printed (each entry tagged by kind) and
+    the user picks by number. Returns ``None`` only when the interactive pick
+    is aborted; raises a typed fault for a named-but-unknown provider."""
+    if named is not None:
+        target = _make_signin_target(named.strip().lower())
+        if target is None:
+            raise _FaultSignal(
+                credential_fault(
+                    "unknown-provider",
+                    f"Unknown provider: {named}.",
+                    hint="Run the command with no provider to list the choices.",
+                )
+            )
+        return target
+
+    directory = list_login_providers()
+    io.print("Available providers:")
+    for index, entry in enumerate(directory):
+        kind = "browser sign-in" if entry.auth_kind == "oauth" else "api key"
+        io.print(f"  {index + 1}. {entry.label} ({kind})")
+    answer = await io.ask("Select a provider by number: ")
+    if len(answer) == 0:
+        return None
+    index = _parse_pick(answer)
+    if index is None or index < 0 or index >= len(directory):
+        raise _FaultSignal(
+            credential_fault(
+                "unknown-provider", "That is not one of the listed providers."
+            )
+        )
+    return _make_signin_target(directory[index].id)
+
+
+async def _do_signin(
+    target: _SigninTarget,
+    requested_account: str | None,
+    method: SigninMethod | None,
+    vault: AuthVault,
+    io: CredentialIo,
+) -> CredentialFault | None:
+    """The sign-in flow for a resolved target.
+
+    Routes by method: a browser sign-in for an OAuth-capable provider, or the
+    api-key flow otherwise. When no method is given and the provider supports
+    both, the browser path is preferred; an explicit ``--method`` always wins
+    (and a browser request against a provider that cannot sign in that way is
+    a typed fault). Returns a typed fault on any rejection."""
+    account = requested_account if requested_account is not None else _DEFAULT_ACCOUNT
+    account_fault = validate_account_name(account)
+    if account_fault is not None:
+        return account_fault
+
+    existing = await vault.list_accounts(target.id)
+    if account in existing:
+        return credential_fault(
+            "name-collision",
+            f'An account named "{account}" already exists for {target.label}.',
+            hint="Pass --account with a different name, or sign out first.",
+        )
+
+    # Choose the path. Prefer browser sign-in when the provider supports it
+    # and no explicit method was requested; honour an explicit method
+    # otherwise.
+    use_oauth = method == "oauth" or (method is None and target.oauth_capable)
+
+    if use_oauth:
+        if not target.oauth_capable:
+            return credential_fault(
+                "unknown-provider",
+                f"{target.label} does not support browser sign-in.",
+                hint="Re-run with --method api-key to store an api key instead.",
+            )
+        return await _do_oauth_signin(target, account, vault, io)
+
+    if target.api_key_entry is None:
+        return credential_fault(
+            "unknown-provider",
+            f"{target.label} has no api-key sign-in; use browser sign-in instead.",
+            hint="Re-run with --method oauth.",
+        )
+    return await _do_api_key_signin(
+        target.api_key_entry, account, len(existing) == 0, vault, io
+    )
+
+
+async def _do_api_key_signin(
+    provider: ProviderEntry,
+    account: str,
+    make_default: bool,
+    vault: AuthVault,
+    io: CredentialIo,
+) -> CredentialFault | None:
+    """The api-key sign-in sub-flow.
+
+    Consults the env-var override first; if a key is already exported the user
+    is offered to store it directly. Otherwise it prompts for a secret,
+    validates it, and persists through the vault."""
+    env_key = get_env_api_key(provider.id)
+    api_key = env_key.strip() if env_key is not None else ""
+    if len(api_key) > 0:
+        io.print(f"Found {provider.env_key} in the environment for {provider.label}.")
+        use_env = await io.ask("Store the environment key? [Y/n] ")
+        if re.match(r"^n", use_env, re.IGNORECASE) is not None:
+            api_key = ""
+
+    if len(api_key) == 0:
+        io.print(f"Obtain a key at {provider.docs_url}")
+        api_key = await io.ask_secret(f"Enter the {provider.label} api key: ")
+
+    key_fault = validate_api_key(api_key)
+    if key_fault is not None:
+        return key_fault
+
+    await vault.put_api_key(provider.id, account, api_key.strip(), make_default)
+
+    suffix = " (default)" if make_default else ""
+    io.print(f'Stored {provider.label} key under account "{account}"{suffix}.')
+    return None
+
+
+async def _do_oauth_signin(
+    target: _SigninTarget,
+    account: str,
+    vault: AuthVault,
+    io: CredentialIo,
+) -> CredentialFault | None:
+    """The browser sign-in sub-flow.
+
+    Drives the adapter's login through :func:`~.oauth.start_oauth_login`,
+    opening the consent url in the user's browser and relaying any interactive
+    prompt the flow raises through the injected io. A failure of the flow
+    surfaces as a typed ``vault`` fault so the command exit path is uniform."""
+    io.print(f"Starting browser sign-in for {target.label}...")
+
+    async def on_auth(info: OAuthAuthorization) -> None:
+        opened = await open_login_url(info.url)
+        io.print(f"{'Opened' if opened else 'Open this url'}: {info.url}")
+        if info.instructions is not None:
+            io.print(info.instructions)
+
+    def on_prompt(prompt: OAuthPrompt) -> Awaitable[str]:
+        return io.ask(f"{prompt.message} ")
+
+    try:
+        result = await start_oauth_login(
+            target.id,
+            OAuthLoginCallbacks(
+                on_auth=on_auth,
+                on_prompt=on_prompt,
+                on_progress=io.print,
+            ),
+            vault,
+            account,
+        )
+        suffix = " (default)" if result.made_default else ""
+        io.print(f'Signed in to {target.label} under account "{result.account}"{suffix}.')
+        return None
+    except Exception as cause:
+        message = str(cause) if isinstance(cause, Exception) else "The browser sign-in failed."
+        return credential_fault(
+            "vault",
+            f"Browser sign-in failed: {message}",
+            hint="Try again, or use --method api-key to store an api key instead.",
+            cause=cause,
+        )
+
+
+async def _do_signout(
+    provider: ProviderEntry,
+    requested_account: str | None,
+    vault: AuthVault,
+    io: CredentialIo,
+) -> CredentialFault | None:
+    """The sign-out flow for a resolved provider.
+
+    Removes the named account (or every account for the provider when none is
+    named). Returns a ``not-found`` fault when nothing was stored for the
+    target."""
+    if requested_account is not None:
+        account_fault = validate_account_name(requested_account)
+        if account_fault is not None:
+            return account_fault
+
+    removed = await vault.remove(provider.id, requested_account)
+    if not removed:
+        scope = (
+            f'account "{requested_account}"'
+            if requested_account is not None
+            else "any account"
+        )
+        return credential_fault(
+            "not-found", f"No stored credential for {provider.label} ({scope})."
+        )
+
+    io.print(
+        f'Removed {provider.label} account "{requested_account}".'
+        if requested_account is not None
+        else f"Removed all {provider.label} credentials."
+    )
+    return None
+
+
+def format_credential_fault(fault: CredentialFault) -> str:
+    """Render a :class:`~.contract.CredentialFault` as the single human-facing
+    message the caller prints before exiting non-zero. Pure; no I/O."""
+    head = f"{_fault_label(fault.kind)}: {fault.message}"
+    return f"{head}\n  {fault.hint}" if fault.hint is not None else head
+
+
+def _fault_label(kind: CredentialFaultKind) -> str:
+    """A short human label for a :data:`~.contract.CredentialFaultKind`."""
+    match kind:
+        case "unknown-provider":
+            return "Unknown provider"
+        case "invalid-key":
+            return "Invalid api key"
+        case "invalid-account":
+            return "Invalid account name"
+        case "name-collision":
+            return "Account already exists"
+        case "not-found":
+            return "Nothing to remove"
+        case "vault":
+            return "Credential store error"
+        case "aborted":
+            return "Cancelled"
+        case _:  # pragma: no cover - closed union
+            return "Error"