kstlib 0.0.1a0__py3-none-any.whl → 1.0.0__py3-none-any.whl

kstlib/cli/app.py

@@ -0,0 +1,195 @@
+"""Command-line interface for kstlib.
+
+This module provides the CLI commands using Typer and Rich for enhanced terminal output.
+Available commands:
+- info: Display package information and logo
+- version: Show package version
+"""
+
+# pylint: disable=redefined-builtin
+# Reason: Rich.print is imported to override builtin print for enhanced output
+
+import logging
+from typing import Annotated
+
+import typer
+from rich import print
+from rich.table import Table
+
+from kstlib import meta
+from kstlib.cli.commands.auth import register_cli as register_auth_cli
+from kstlib.cli.commands.config import register_cli as register_config_cli
+from kstlib.cli.commands.ops import register_cli as register_ops_cli
+from kstlib.cli.commands.rapi import register_cli as register_rapi_cli
+from kstlib.cli.commands.secrets import register_cli as register_secrets_cli
+from kstlib.cli.commands.secrets import shred as secrets_shred
+from kstlib.cli.common import console
+from kstlib.logging import LogManager, get_logger, init_logging
+
+app = typer.Typer(add_completion=False, name=meta.__app_name__)
+
+# Global logger instance (initialized in main callback)
+_cli_logger: LogManager | None = None
+
+# Valid log levels
+LOG_LEVELS = ["TRACE", "DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"]
+
+# Verbose flag mapping: -v=INFO, -vv=DEBUG, -vvv=TRACE
+VERBOSE_LEVELS = {
+    0: "WARNING",  # Default
+    1: "INFO",  # -v
+    2: "DEBUG",  # -vv
+    3: "TRACE",  # -vvv
+}
+
+
+def _version_callback(value: bool) -> None:
+    """Display version and exit if requested.
+
+    Args:
+        value: True if --version flag was passed.
+
+    Raises:
+        typer.Exit: Always exits after showing version.
+    """
+    if value:
+        print(f"{meta.__version__}")
+        raise typer.Exit()
+
+
+def get_cli_logger() -> logging.Logger:
+    """Get the CLI logger instance.
+
+    Returns:
+        The CLI logger. Uses the global kstlib logger if initialized
+        via --log-level, otherwise returns a standard logger.
+    """
+    return get_logger("cli")
+
+
+@app.callback()
+def main(  # pylint: disable=unused-argument
+    version: bool | None = typer.Option(
+        None,
+        "--version",
+        help="Show the application's version and exit.",
+        callback=_version_callback,
+        is_eager=True,
+    ),
+    log_level: Annotated[
+        str | None,
+        typer.Option(
+            "--log-level",
+            "-l",
+            help="Set logging level (TRACE, DEBUG, INFO, WARNING, ERROR, CRITICAL).",
+            case_sensitive=False,
+        ),
+    ] = None,
+    log_file: Annotated[
+        bool,
+        typer.Option(
+            "--log-file",
+            help="Enable file logging (writes to ./logs/kstlib.log by default).",
+        ),
+    ] = False,
+    verbose: Annotated[
+        int,
+        typer.Option(
+            "--verbose",
+            "-v",
+            count=True,
+            help="Increase verbosity (-v=INFO, -vv=DEBUG, -vvv=TRACE).",
+        ),
+    ] = 0,
+) -> None:
+    """Initialize the root Typer app and handle --version eagerly."""
+    global _cli_logger
+
+    # Determine log level (priority: --log-level > -v > default)
+    if log_level is not None:
+        # Explicit --log-level takes precedence
+        level = log_level.upper()
+        if level not in LOG_LEVELS:
+            console.print(f"[red]Invalid log level: {log_level}[/]")
+            console.print(f"[dim]Valid levels: {', '.join(LOG_LEVELS)}[/]")
+            raise typer.Exit(1)
+    elif verbose > 0:
+        # -v/-vv/-vvv flags
+        level = VERBOSE_LEVELS.get(min(verbose, 3), "TRACE")
+    else:
+        level = "WARNING"  # Default: only warnings and errors
+
+    # Determine output mode
+    output = "both" if log_file else "console"
+
+    # Always initialize logging so handlers are configured
+    _cli_logger = init_logging(
+        config={
+            "console": {"level": level},
+            "file": {"level": level},
+            "output": output,
+        },
+    )
+
+    if log_level is not None or verbose > 0:
+        source = "--log-level" if log_level is not None else f"-{'v' * verbose}"
+        _cli_logger.debug("CLI logging initialized", level=level, source=source)
+
+
+@app.command()
+def info(
+    full: bool = typer.Option(
+        False,
+        "--full",
+        "-f",
+        help="Show full information about the application.",
+    ),
+) -> None:
+    """Display package information and logo.
+
+    Args:
+        full: If True, show detailed package metadata including author, license, etc.
+    """
+    print(meta.__logo__)
+
+    if full:
+        _data = [
+            ("Name", meta.__app_name__),
+            ("Version", meta.__version__),
+            ("Description", meta.__description__),
+            ("Author", meta.__author__),
+            ("Email", meta.__email__),
+            ("URL", meta.__url__),
+            ("Keywords", ", ".join(meta.__keywords__)),
+            ("Classifiers", "\n".join(meta.__classifiers__)),
+            ("License Type", meta.__license_type__),
+            ("License", meta.__license__),
+            ("", ""),
+        ]
+
+        table = Table(show_header=False, show_lines=False, title=None, box=None)
+        table.add_column(justify="right")
+        table.add_column(justify="left")
+
+        for row in _data:
+            table.add_row(f"[light_salmon1]{row[0]}[/]", row[1])
+
+        console.print(table)
+
+        return
+
+    _version_callback(True)
+
+
+register_auth_cli(app)
+register_ops_cli(app)
+register_rapi_cli(app)
+register_secrets_cli(app)
+register_config_cli(app)
+
+# Expose shred as a top-level command for convenience.
+app.command()(secrets_shred)
+
+
+if __name__ == "__main__":
+    app()

kstlib/cli/commands/__init__.py

@@ -0,0 +1,5 @@
+"""CLI command modules for kstlib."""
+
+from __future__ import annotations
+
+__all__: list[str] = []

kstlib/cli/commands/auth/__init__.py

@@ -0,0 +1,39 @@
+"""CLI commands for OAuth2/OIDC authentication."""
+
+from __future__ import annotations
+
+import typer
+
+from .login import login
+from .logout import logout
+from .providers import providers
+from .status import status
+from .token import token
+from .whoami import whoami
+
+auth_app = typer.Typer(help="Manage OAuth2/OIDC authentication.")
+
+# Register commands on the auth_app
+auth_app.command()(login)
+auth_app.command()(logout)
+auth_app.command()(status)
+auth_app.command()(token)
+auth_app.command()(whoami)
+auth_app.command()(providers)
+
+
+def register_cli(app: typer.Typer) -> None:
+    """Register the auth sub-commands on the root Typer app."""
+    app.add_typer(auth_app, name="auth")
+
+
+__all__ = [
+    "auth_app",
+    "login",
+    "logout",
+    "providers",
+    "register_cli",
+    "status",
+    "token",
+    "whoami",
+]

kstlib/cli/commands/auth/common.py

@@ -0,0 +1,122 @@
+"""Shared utilities for auth CLI commands."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import typer
+
+from kstlib.auth.config import get_default_provider_name, list_configured_providers
+from kstlib.auth.errors import AuthError, ConfigurationError
+from kstlib.cli.common import exit_error
+
+if TYPE_CHECKING:
+    from kstlib.auth.providers.base import AbstractAuthProvider
+
+# Common CLI options
+PROVIDER_ARGUMENT = typer.Argument(
+    None,
+    help="Provider name (uses default if not specified).",
+    show_default=False,
+)
+
+QUIET_OPTION = typer.Option(
+    False,
+    "--quiet",
+    "-q",
+    help="Suppress verbose output.",
+)
+
+TIMEOUT_OPTION = typer.Option(
+    120,
+    "--timeout",
+    "-t",
+    help="Timeout in seconds for browser authentication.",
+)
+
+
+def resolve_provider_name(provider: str | None) -> str:
+    """Resolve provider name from argument or default.
+
+    Args:
+        provider: Explicit provider name or None.
+
+    Returns:
+        Resolved provider name.
+
+    Raises:
+        typer.Exit: If no provider specified and no default configured.
+    """
+    if provider:
+        return provider
+
+    default = get_default_provider_name()
+    if default:
+        return default
+
+    configured = list_configured_providers()
+    if not configured:
+        return exit_error(
+            "No auth providers configured.\nConfigure providers in kstlib.conf.yml under 'auth.providers'."
+        )
+
+    if len(configured) == 1:
+        return configured[0]
+
+    return exit_error(
+        f"Multiple providers configured: {', '.join(configured)}\n"
+        "Specify a provider name or set 'auth.default_provider' in config."
+    )
+
+
+def get_provider(provider_name: str) -> AbstractAuthProvider:
+    """Get a configured auth provider by name.
+
+    Args:
+        provider_name: Name of the provider.
+
+    Returns:
+        Configured provider instance.
+
+    Raises:
+        typer.Exit: If provider not found or misconfigured.
+    """
+    from kstlib.auth.config import get_provider_config
+
+    provider_cfg = get_provider_config(provider_name)
+    if provider_cfg is None:
+        configured = list_configured_providers()
+        if configured:
+            exit_error(f"Provider '{provider_name}' not found.\nAvailable providers: {', '.join(configured)}")
+        else:
+            exit_error(f"Provider '{provider_name}' not found.\nNo providers configured in kstlib.conf.yml.")
+
+    # Determine provider type and instantiate
+    provider_type = provider_cfg.get("type", "oidc").lower()
+
+    try:
+        if provider_type in ("oidc", "openid", "openidconnect"):
+            from kstlib.auth.providers.oidc import OIDCProvider
+
+            return OIDCProvider.from_config(provider_name)
+
+        if provider_type in ("oauth2", "oauth"):
+            from kstlib.auth.providers.oauth2 import OAuth2Provider
+
+            return OAuth2Provider.from_config(provider_name)
+
+        exit_error(f"Unknown provider type '{provider_type}' for '{provider_name}'.")
+
+    except ConfigurationError as e:
+        exit_error(f"Configuration error for '{provider_name}': {e}")
+    except AuthError as e:
+        exit_error(f"Auth error for '{provider_name}': {e}")
+
+
+__all__ = [
+    "PROVIDER_ARGUMENT",
+    "QUIET_OPTION",
+    "TIMEOUT_OPTION",
+    "get_provider",
+    "resolve_provider_name",
+]

kstlib/cli/commands/auth/login.py

@@ -0,0 +1,325 @@
+"""Authenticate with an OAuth2/OIDC provider."""
+
+# pylint: disable=too-many-branches,too-many-statements
+# Justification: OAuth2 login flow with multiple user-facing modes (quiet/verbose,
+# browser/no-browser/manual, PKCE/standard) and comprehensive error handling. Each
+# branch handles a distinct case - decomposing would obscure the linear auth flow.
+
+from __future__ import annotations
+
+import re
+import webbrowser
+from typing import TYPE_CHECKING
+
+# Note: parse_qs not used - it converts + to space, breaking base64 codes
+import typer
+from rich.panel import Panel
+from rich.prompt import Prompt
+
+from kstlib.auth.callback import CallbackServer
+from kstlib.auth.config import get_callback_server_config
+from kstlib.auth.errors import AuthError, CallbackServerError, TokenExchangeError
+from kstlib.cli.common import CommandResult, CommandStatus, console, exit_error, render_result
+
+from .common import PROVIDER_ARGUMENT, QUIET_OPTION, TIMEOUT_OPTION, get_provider, resolve_provider_name
+
+if TYPE_CHECKING:
+    from kstlib.auth.providers.base import AbstractAuthProvider
+
+
+# Defense in depth: limits for manual input
+_MAX_INPUT_LENGTH = 8192  # Max URL/code input length (increased for long base64 codes)
+_MAX_CODE_LENGTH = 2048  # Max authorization code length (some IdPs use long base64 codes)
+_CODE_PATTERN = re.compile(r"^[a-zA-Z0-9._~+/=-]+$")  # RFC 6749 safe chars + base64
+
+
+def _extract_code_from_input(user_input: str) -> tuple[str | None, str | None]:
+    """Extract authorization code and state from user input.
+
+    Handles both full redirect URLs and raw code values.
+    Applies defense-in-depth validation on extracted values.
+
+    Args:
+        user_input: URL with code parameter or raw code value.
+
+    Returns:
+        Tuple of (code, state) where state may be None.
+    """
+    user_input = user_input.strip()
+
+    # Defense: limit input length to prevent DoS
+    if len(user_input) > _MAX_INPUT_LENGTH:
+        return None, None
+
+    code: str | None = None
+    state: str | None = None
+
+    # Extract code and state via regex (preserves + and / in base64 codes)
+    # Note: parse_qs converts + to space, breaking base64-encoded codes
+    code_match = re.search(r"[?&]code=([^&\s]+)", user_input)
+    if code_match:
+        code = code_match.group(1)
+        state_match = re.search(r"[?&]state=([^&\s]+)", user_input)
+        state = state_match.group(1) if state_match else None
+
+    # Assume raw code value (no URL structure)
+    if not code and user_input and not user_input.startswith(("?", "&", "=")):
+        code = user_input
+
+    # Defense: validate code format and length
+    if code:
+        if len(code) > _MAX_CODE_LENGTH:
+            return None, None
+        if not _CODE_PATTERN.match(code):
+            return None, None
+
+    return code, state
+
+
+def _login_manual(
+    auth_provider: AbstractAuthProvider,
+    provider_name: str,
+    quiet: bool,
+) -> None:
+    """Perform manual login without callback server.
+
+    Displays the authorization URL and prompts for the redirect URL or code.
+
+    Args:
+        auth_provider: The authentication provider instance.
+        provider_name: Name of the provider for display.
+        quiet: Suppress verbose output.
+    """
+    # Generate authorization URL (with PKCE if supported)
+    if hasattr(auth_provider, "get_authorization_url_with_pkce"):
+        auth_url, state, code_verifier = auth_provider.get_authorization_url_with_pkce()
+    else:
+        auth_url, state = auth_provider.get_authorization_url()
+        code_verifier = None
+
+    # Display instructions and URL
+    console.print(
+        Panel(
+            "[bold]Manual authentication mode[/]\n\n"
+            "1. Copy the URL below and open it in your browser\n"
+            "2. Complete the authentication\n"
+            "3. Copy the redirect URL from your browser (even if it shows an error)\n"
+            "4. Paste it below",
+            title="Manual Login",
+            style="cyan",
+        )
+    )
+    console.print()
+    console.print("[bold]Authorization URL:[/]")
+    console.print(f"\n{auth_url}\n", soft_wrap=True, highlight=False)
+
+    # Prompt for redirect URL or code
+    console.print("[bold]After authentication, paste the redirect URL or code:[/]")
+    user_input = Prompt.ask("[dim](paste URL or code)[/]")
+
+    if not user_input:
+        exit_error("No input provided.")
+
+    # Extract code from input
+    code, returned_state = _extract_code_from_input(user_input)
+
+    if not code:
+        exit_error(
+            "Could not extract authorization code from input.\nExpected a URL with ?code=... or the raw code value."
+        )
+
+    # Validate state if returned
+    if returned_state and returned_state != state:
+        exit_error("State mismatch - possible CSRF attack.")
+
+    # Exchange code for token
+    if not quiet:
+        console.print("[dim]Exchanging authorization code for token...[/]")
+
+    try:
+        token = auth_provider.exchange_code(
+            code=code,
+            state=state,
+            code_verifier=code_verifier,
+        )
+    except TokenExchangeError as e:
+        exit_error(f"Token exchange failed: {e}")
+
+    # Success
+    render_result(
+        CommandResult(
+            status=CommandStatus.OK,
+            message=f"Successfully authenticated with {provider_name}.",
+            payload={
+                "provider": provider_name,
+                "token_type": token.token_type.value if hasattr(token.token_type, "value") else str(token.token_type),
+                "expires_in": token.expires_in,
+                "scopes": token.scope,
+            }
+            if not quiet
+            else None,
+        )
+    )
+
+
+def _login_with_callback(
+    auth_provider: AbstractAuthProvider,
+    provider_name: str,
+    quiet: bool,
+    timeout: int,
+    no_browser: bool,
+) -> None:
+    """Perform login using local callback server.
+
+    Args:
+        auth_provider: The authentication provider instance.
+        provider_name: Name of the provider for display.
+        quiet: Suppress verbose output.
+        timeout: Callback timeout in seconds.
+        no_browser: Print URL instead of opening browser.
+    """
+    callback_cfg = get_callback_server_config()
+
+    with CallbackServer(
+        host=callback_cfg["host"],
+        port=callback_cfg["port"],
+    ) as server:
+        # Generate authorization URL
+        if hasattr(auth_provider, "get_authorization_url_with_pkce"):
+            auth_url, state, code_verifier = auth_provider.get_authorization_url_with_pkce()
+        else:
+            auth_url, state = auth_provider.get_authorization_url()
+            code_verifier = None
+
+        if no_browser:
+            console.print(
+                Panel(
+                    "Open this URL in your browser:",
+                    title="Authorization URL",
+                    style="cyan",
+                )
+            )
+            console.print(f"\n{auth_url}\n", soft_wrap=True, highlight=False)
+        else:
+            if not quiet:
+                console.print(f"[dim]Opening browser for {provider_name} authentication...[/]")
+            webbrowser.open(auth_url)
+
+        if not quiet:
+            console.print(f"[dim]Waiting for callback (timeout: {timeout}s)...[/]")
+
+        # Wait for callback
+        result = server.wait_for_callback(timeout=timeout)
+
+        if result.error:
+            exit_error(f"Authorization failed: {result.error_description or result.error}")
+
+        if result.code is None:
+            exit_error("No authorization code received.")
+
+        # Validate state
+        if result.state != state:
+            exit_error("State mismatch - possible CSRF attack.")
+
+        # Exchange code for token
+        if not quiet:
+            console.print("[dim]Exchanging authorization code for token...[/]")
+
+        token = auth_provider.exchange_code(
+            code=result.code,
+            state=state,
+            code_verifier=code_verifier,
+        )
+
+        # Success
+        render_result(
+            CommandResult(
+                status=CommandStatus.OK,
+                message=f"Successfully authenticated with {provider_name}.",
+                payload={
+                    "provider": provider_name,
+                    "token_type": token.token_type.value
+                    if hasattr(token.token_type, "value")
+                    else str(token.token_type),
+                    "expires_in": token.expires_in,
+                    "scopes": token.scope,
+                }
+                if not quiet
+                else None,
+            )
+        )
+
+
+def login(  # noqa: PLR0913
+    provider: str | None = PROVIDER_ARGUMENT,
+    quiet: bool = QUIET_OPTION,
+    timeout: int = TIMEOUT_OPTION,
+    no_browser: bool = typer.Option(
+        False,
+        "--no-browser",
+        help="Print authorization URL instead of opening browser.",
+    ),
+    manual: bool = typer.Option(
+        False,
+        "--manual",
+        "-m",
+        help="Manual mode: display URL and prompt for code (no callback server).",
+    ),
+    force: bool = typer.Option(
+        False,
+        "--force",
+        "-f",
+        help="Force re-authentication even if already authenticated.",
+    ),
+) -> None:
+    """Authenticate with an OAuth2/OIDC provider.
+
+    Opens the system browser to complete the OAuth2 authorization flow.
+    Use --manual when the callback server cannot bind (e.g., port 443 in corporate environments).
+    """
+    provider_name = resolve_provider_name(provider)
+    auth_provider = get_provider(provider_name)
+
+    # Check if already authenticated
+    if not force and auth_provider.is_authenticated:
+        if quiet:
+            console.print(f"[green]{provider_name}: already authenticated[/]")
+        else:
+            console.print(
+                Panel(
+                    f"Already authenticated with [cyan]{provider_name}[/].\nUse [bold]--force[/] to re-authenticate.",
+                    title="Auth Status",
+                    style="green",
+                )
+            )
+        return
+
+    try:
+        if manual:
+            _login_manual(auth_provider, provider_name, quiet)
+        else:
+            _login_with_callback(auth_provider, provider_name, quiet, timeout, no_browser)
+
+    except CallbackServerError as e:
+        # Suggest manual mode if callback server fails
+        console.print(
+            Panel(
+                f"[red]{e}[/]\n\n"
+                "[yellow]Tip:[/] Use [bold]--manual[/] mode to authenticate without a callback server:\n"
+                f"  kstlib auth login --manual {provider_name}",
+                title="Callback Server Error",
+                style="red",
+            )
+        )
+        raise typer.Exit(1) from None
+    except TokenExchangeError as e:
+        exit_error(f"Token exchange failed: {e}")
+    except AuthError as e:
+        exit_error(f"Authentication failed: {e}")
+    except TimeoutError:
+        exit_error(f"Authentication timed out after {timeout} seconds.")
+    except KeyboardInterrupt:
+        exit_error("Authentication cancelled by user.")
+
+
+__all__ = ["login"]