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

kstlib/cli/commands/auth/logout.py

@@ -0,0 +1,74 @@
+"""Logout from an OAuth2/OIDC provider."""
+
+from __future__ import annotations
+
+import typer
+
+from kstlib.cli.common import CommandResult, CommandStatus, console, render_result
+
+from .common import PROVIDER_ARGUMENT, QUIET_OPTION, get_provider, resolve_provider_name
+
+
+def logout(
+    provider: str | None = PROVIDER_ARGUMENT,
+    quiet: bool = QUIET_OPTION,
+    revoke: bool = typer.Option(
+        True,
+        "--revoke/--no-revoke",
+        help="Attempt to revoke token at the authorization server.",
+    ),
+) -> None:
+    """Logout from an OAuth2/OIDC provider.
+
+    Clears the stored token and optionally revokes it at the server.
+    """
+    provider_name = resolve_provider_name(provider)
+    auth_provider = get_provider(provider_name)
+
+    # Check if authenticated
+    token = auth_provider.get_token(auto_refresh=False)
+    if token is None:
+        if quiet:
+            console.print(f"[yellow]{provider_name}: not authenticated[/]")
+        else:
+            render_result(
+                CommandResult(
+                    status=CommandStatus.WARNING,
+                    message=f"Not authenticated with {provider_name}.",
+                )
+            )
+        return
+
+    # Attempt revocation if requested
+    revoked = False
+    if revoke:
+        if not quiet:
+            console.print(f"[dim]Revoking token for {provider_name}...[/]")
+        try:
+            revoked = auth_provider.revoke(token)
+        except Exception:  # pylint: disable=broad-exception-caught
+            # Best-effort revocation
+            if not quiet:
+                console.print("[dim]Token revocation not supported or failed.[/]")
+
+    # Clear token from storage
+    auth_provider.clear_token()
+
+    # Success message
+    if revoked:
+        message = f"Logged out from {provider_name} (token revoked)."
+    else:
+        message = f"Logged out from {provider_name} (token cleared locally)."
+
+    if quiet:
+        console.print(f"[green]{message}[/]")
+    else:
+        render_result(
+            CommandResult(
+                status=CommandStatus.OK,
+                message=message,
+            )
+        )
+
+
+__all__ = ["logout"]

kstlib/cli/commands/auth/providers.py

@@ -0,0 +1,57 @@
+"""List configured auth providers."""
+
+from __future__ import annotations
+
+import typer
+from rich.table import Table
+
+from kstlib.auth.config import (
+    get_default_provider_name,
+    get_provider_config,
+    list_configured_providers,
+)
+from kstlib.cli.common import console
+
+
+def providers(
+    verbose: bool = typer.Option(
+        False,
+        "--verbose",
+        "-v",
+        help="Show detailed provider configuration.",
+    ),
+) -> None:
+    """List configured authentication providers."""
+    configured = list_configured_providers()
+    default = get_default_provider_name()
+
+    if not configured:
+        console.print("[yellow]No auth providers configured.[/]")
+        console.print("Configure providers in kstlib.conf.yml under 'auth.providers'.")
+        raise typer.Exit(0)
+
+    table = Table(title="Configured Auth Providers")
+    table.add_column("Provider", style="cyan")
+    table.add_column("Type", style="green")
+    if verbose:
+        table.add_column("Issuer / Endpoints", style="dim")
+    table.add_column("Default", style="yellow", justify="center")
+
+    for name in configured:
+        cfg = get_provider_config(name) or {}
+        provider_type = cfg.get("type", "oidc").upper()
+        is_default = "[bold]✓[/]" if name == default else ""
+
+        if verbose:
+            # Show issuer or authorization endpoint
+            issuer = cfg.get("issuer", "")
+            auth_endpoint = cfg.get("authorization_endpoint", cfg.get("authorize_url", ""))
+            endpoint_info = issuer or auth_endpoint or "[dim]not configured[/]"
+            table.add_row(name, provider_type, endpoint_info, is_default)
+        else:
+            table.add_row(name, provider_type, is_default)
+
+    console.print(table)
+
+
+__all__ = ["providers"]

kstlib/cli/commands/auth/status.py

@@ -0,0 +1,291 @@
+"""Show authentication status for a provider."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime, timedelta, timezone
+from typing import TYPE_CHECKING
+
+from rich.panel import Panel
+from rich.table import Table
+
+from kstlib.auth.config import get_status_config
+from kstlib.cli.common import console
+
+from .common import PROVIDER_ARGUMENT, QUIET_OPTION, get_provider, resolve_provider_name
+
+if TYPE_CHECKING:
+    from kstlib.auth.models import Token
+
+
+@dataclass(frozen=True, slots=True)
+class _DisplayContext:
+    """Display context for status output."""
+
+    provider_name: str
+    status_text: str
+    status_style: str
+    threshold: int
+    refresh_threshold: int
+    use_local_tz: bool
+    is_expired: bool
+
+
+def _format_duration(seconds: int) -> str:
+    """Format duration in human-readable form.
+
+    Args:
+        seconds: Duration in seconds (can be negative for past).
+
+    Returns:
+        Formatted duration string.
+    """
+    abs_seconds = abs(seconds)
+    if abs_seconds > 3600:
+        return f"{abs_seconds // 3600}h {(abs_seconds % 3600) // 60}m"
+    if abs_seconds > 60:
+        return f"{abs_seconds // 60}m {abs_seconds % 60}s"
+    return f"{abs_seconds}s"
+
+
+def _format_datetime(dt: datetime, *, use_local: bool) -> str:
+    """Format datetime for display.
+
+    Args:
+        dt: Datetime to format (should be timezone-aware).
+        use_local: If True, convert to local timezone.
+
+    Returns:
+        Formatted datetime string.
+    """
+    if use_local:
+        local_dt = dt.astimezone()
+        return local_dt.strftime("%Y-%m-%d %H:%M:%S %Z")
+    return dt.strftime("%Y-%m-%d %H:%M:%S UTC")
+
+
+def _get_refresh_token_expiry(token: Token) -> datetime | None:
+    """Extract refresh token expiry from token metadata.
+
+    Args:
+        token: Token object with potential refresh token info.
+
+    Returns:
+        Refresh token expiry datetime, or None if unknown.
+    """
+    metadata = token.metadata
+
+    # Check for refresh_expires_at (absolute timestamp)
+    if metadata.get("refresh_expires_at"):
+        try:
+            return datetime.fromisoformat(str(metadata["refresh_expires_at"]))
+        except (ValueError, TypeError):
+            pass
+
+    # Check refresh_expires_in from token response (relative)
+    if metadata.get("refresh_expires_in"):
+        try:
+            return token.issued_at + timedelta(seconds=int(metadata["refresh_expires_in"]))
+        except (ValueError, TypeError):
+            pass
+
+    return None
+
+
+def _determine_status(token: Token, threshold: int) -> tuple[str, str, bool]:
+    """Determine token status text and style.
+
+    Args:
+        token: Token to check.
+        threshold: Expiring soon threshold in seconds.
+
+    Returns:
+        Tuple of (status_text, status_style, is_expired).
+    """
+    expires_in = token.expires_in
+    is_expired = token.is_expired
+
+    if is_expired:
+        return "[red]Expired[/]", "red", True
+    if expires_in is not None and expires_in <= threshold:
+        return "[yellow]Expiring soon[/]", "yellow", False
+    return "[green]Valid[/]", "green", False
+
+
+def _build_access_token_rows(table: Table, token: Token, ctx: _DisplayContext) -> None:
+    """Add access token rows to the status table.
+
+    Args:
+        table: Rich table to add rows to.
+        token: Token object.
+        ctx: Display context.
+    """
+    table.add_row("Provider", f"[cyan]{ctx.provider_name}[/]")
+    table.add_row("Status", ctx.status_text)
+    table.add_row(
+        "Token Type",
+        token.token_type.value if hasattr(token.token_type, "value") else str(token.token_type),
+    )
+
+    if token.issued_at:
+        table.add_row("Issued At", _format_datetime(token.issued_at, use_local=ctx.use_local_tz))
+
+    if token.expires_at:
+        table.add_row("Expires At", _format_datetime(token.expires_at, use_local=ctx.use_local_tz))
+
+    expires_in = token.expires_in
+    if expires_in is not None:
+        if ctx.is_expired:
+            table.add_row("Expired Since", f"[red]{_format_duration(expires_in)}[/]")
+        else:
+            table.add_row("Expires In", _format_duration(expires_in))
+
+    if token.scope:
+        table.add_row("Scopes", " ".join(token.scope))
+
+
+def _build_refresh_token_panel(token: Token, ctx: _DisplayContext) -> Panel | None:
+    """Build a separate panel for refresh token status.
+
+    Args:
+        token: Token object.
+        ctx: Display context.
+
+    Returns:
+        Panel for refresh token, or None if no refresh token.
+    """
+    if not token.is_refreshable:
+        return None
+
+    table = Table(show_header=False, box=None)
+    table.add_column("Field", style="dim")
+    table.add_column("Value")
+
+    refresh_expiry = _get_refresh_token_expiry(token)
+
+    if not refresh_expiry:
+        table.add_row("Status", "[green]Available[/]")
+        table.add_row("Expires At", "[dim]Unknown[/]")
+        return Panel(table, title="Refresh Token", style="green")
+
+    now = datetime.now(timezone.utc)
+    refresh_expires_in = int((refresh_expiry - now).total_seconds())
+
+    if refresh_expires_in <= 0:
+        status_text = "[red]Expired[/]"
+        panel_style = "red"
+    elif refresh_expires_in <= ctx.refresh_threshold:
+        status_text = "[yellow]Expiring soon[/]"
+        panel_style = "yellow"
+    else:
+        status_text = "[green]Valid[/]"
+        panel_style = "green"
+
+    table.add_row("Status", status_text)
+    table.add_row("Expires At", _format_datetime(refresh_expiry, use_local=ctx.use_local_tz))
+
+    if refresh_expires_in <= 0:
+        table.add_row("Expired Since", f"[red]{_format_duration(refresh_expires_in)}[/]")
+    else:
+        table.add_row("Expires In", _format_duration(refresh_expires_in))
+
+    return Panel(table, title="Refresh Token", style=panel_style)
+
+
+def _show_not_authenticated(provider_name: str, quiet: bool) -> None:
+    """Display not authenticated message.
+
+    Args:
+        provider_name: Provider name.
+        quiet: Whether to use quiet mode.
+    """
+    if quiet:
+        console.print(f"[yellow]{provider_name}: not authenticated[/]")
+    else:
+        console.print(
+            Panel(
+                f"Not authenticated with [cyan]{provider_name}[/].\n"
+                f"Run [bold]kstlib auth login {provider_name}[/] to authenticate.",
+                title="Auth Status",
+                style="yellow",
+            )
+        )
+
+
+def _show_quiet_status(provider_name: str, token: Token, status_text: str, is_expired: bool) -> None:
+    """Display quiet mode status.
+
+    Args:
+        provider_name: Provider name.
+        token: Token object.
+        status_text: Formatted status text.
+        is_expired: Whether token is expired.
+    """
+    expires_in = token.expires_in
+    if expires_in is not None:
+        duration = _format_duration(expires_in)
+        if is_expired:
+            console.print(f"{provider_name}: {status_text} (expired {duration} ago)")
+        else:
+            console.print(f"{provider_name}: {status_text} (expires in {duration})")
+    else:
+        console.print(f"{provider_name}: {status_text}")
+
+
+def _show_verbose_status(token: Token, ctx: _DisplayContext) -> None:
+    """Display verbose mode status.
+
+    Args:
+        token: Token object.
+        ctx: Display context.
+    """
+    # Access token panel
+    table = Table(show_header=False, box=None)
+    table.add_column("Field", style="dim")
+    table.add_column("Value")
+    _build_access_token_rows(table, token, ctx)
+    console.print(Panel(table, title="Access Token", style=ctx.status_style))
+
+    # Refresh token panel (separate, with its own status color)
+    refresh_panel = _build_refresh_token_panel(token, ctx)
+    if refresh_panel:
+        console.print(refresh_panel)
+
+
+def status(
+    provider: str | None = PROVIDER_ARGUMENT,
+    quiet: bool = QUIET_OPTION,
+) -> None:
+    """Show authentication status for a provider."""
+    provider_name = resolve_provider_name(provider)
+    auth_provider = get_provider(provider_name)
+    token = auth_provider.get_token(auto_refresh=False)
+
+    if token is None:
+        _show_not_authenticated(provider_name, quiet)
+        return
+
+    status_cfg = get_status_config()
+    threshold = status_cfg["expiring_soon_threshold"]
+    refresh_threshold = status_cfg["refresh_expiring_soon_threshold"]
+    use_local_tz = status_cfg["display_timezone"] == "local"
+
+    status_text, status_style, is_expired = _determine_status(token, threshold)
+
+    if quiet:
+        _show_quiet_status(provider_name, token, status_text, is_expired)
+        return
+
+    ctx = _DisplayContext(
+        provider_name=provider_name,
+        status_text=status_text,
+        status_style=status_style,
+        threshold=threshold,
+        refresh_threshold=refresh_threshold,
+        use_local_tz=use_local_tz,
+        is_expired=is_expired,
+    )
+    _show_verbose_status(token, ctx)
+
+
+__all__ = ["status"]

kstlib/cli/commands/auth/token.py

@@ -0,0 +1,199 @@
+"""Show or copy the access token."""
+
+from __future__ import annotations
+
+import base64
+import json
+from typing import Any
+
+import typer
+
+from kstlib.cli.common import console, exit_error
+from kstlib.utils.serialization import to_json
+
+from .common import PROVIDER_ARGUMENT, get_provider, resolve_provider_name
+
+
+def _decode_jwt(token_str: str) -> tuple[dict[str, Any], dict[str, Any]] | None:
+    """Decode a JWT and return (header, payload) dicts.
+
+    Returns None if token is not a valid JWT format.
+    """
+    parts = token_str.split(".")
+    if len(parts) != 3:
+        return None
+
+    try:
+        # Add padding if needed (base64url)
+        def decode_part(part: str) -> dict[str, Any]:
+            # Add padding
+            padding = 4 - len(part) % 4
+            if padding != 4:
+                part += "=" * padding
+            decoded = base64.urlsafe_b64decode(part)
+            return json.loads(decoded)  # type: ignore[no-any-return]
+
+        header = decode_part(parts[0])
+        payload = decode_part(parts[1])
+        return header, payload
+    except Exception:  # pylint: disable=broad-exception-caught
+        return None
+
+
+def _format_decoded(
+    header: dict[str, Any],
+    payload: dict[str, Any],
+    *,
+    as_json: bool = False,
+) -> str:
+    """Format decoded JWT for display."""
+    if as_json:
+        return to_json({"header": header, "payload": payload})
+
+    # YAML-like format (more readable)
+    lines = ["[bold cyan]--- JWT Header ---[/]"]
+    for key, value in header.items():
+        lines.append(f"[dim]{key}:[/] {value}")
+
+    lines.append("")
+    lines.append("[bold cyan]--- JWT Payload ---[/]")
+    for key, value in payload.items():
+        # Special formatting for timestamps
+        if key in ("exp", "iat", "auth_time", "nbf") and isinstance(value, int):
+            from datetime import datetime, timezone
+
+            dt = datetime.fromtimestamp(value, tz=timezone.utc)
+            lines.append(f"[dim]{key}:[/] {value} [dim]({dt.isoformat()})[/]")
+        elif isinstance(value, list):
+            lines.append(f"[dim]{key}:[/] {', '.join(str(v) for v in value)}")
+        else:
+            lines.append(f"[dim]{key}:[/] {value}")
+
+    return "\n".join(lines)
+
+
+def token(
+    provider: str | None = PROVIDER_ARGUMENT,
+    copy: bool = typer.Option(
+        False,
+        "--copy",
+        "-c",
+        help="Copy token to clipboard instead of printing.",
+    ),
+    refresh: bool = typer.Option(
+        False,
+        "--refresh",
+        "-r",
+        help="Force refresh token before displaying.",
+    ),
+    show_refresh: bool = typer.Option(
+        False,
+        "--show-refresh",
+        help="Show the refresh token instead of access token.",
+    ),
+    decode: bool = typer.Option(
+        False,
+        "--decode",
+        "-d",
+        help="Decode JWT and show header + payload (human-readable).",
+    ),
+    as_json: bool = typer.Option(
+        False,
+        "--json",
+        "-j",
+        help="Output decoded JWT as JSON (requires --decode).",
+    ),
+    header: bool = typer.Option(
+        False,
+        "--header",
+        "-H",
+        help="Output as Authorization header value (access token only).",
+    ),
+) -> None:
+    """Show or copy the current access token.
+
+    By default, prints the raw access token. Use --header to get the
+    full Authorization header value (e.g., 'Bearer <token>').
+
+    Use --show-refresh to display the refresh token instead.
+
+    Use --decode to view the JWT header and payload in a readable format.
+    """
+    provider_name = resolve_provider_name(provider)
+    auth_provider = get_provider(provider_name)
+
+    # Force refresh if requested
+    if refresh:
+        current_token = auth_provider.get_token(auto_refresh=False)
+        if current_token is None:
+            exit_error(f"Not authenticated with {provider_name}.\nRun 'kstlib auth login {provider_name}' first.")
+        if not current_token.is_refreshable:
+            exit_error("Token cannot be refreshed (no refresh_token).")
+        try:
+            current_token = auth_provider.refresh(current_token)
+        except Exception as e:  # pylint: disable=broad-exception-caught
+            exit_error(f"Token refresh failed: {e}")
+    else:
+        current_token = auth_provider.get_token(auto_refresh=True)
+
+    if current_token is None:
+        exit_error(f"Not authenticated with {provider_name}.\nRun 'kstlib auth login {provider_name}' first.")
+
+    # Validate incompatible options
+    if as_json and not decode:
+        exit_error("--json requires --decode.")
+    if decode and header:
+        exit_error("--decode and --header cannot be used together.")
+    if decode and copy:
+        exit_error("--decode and --copy cannot be used together.")
+
+    # Handle --show-refresh
+    if show_refresh:
+        if header:
+            exit_error("--header cannot be used with --show-refresh (refresh tokens are not used in headers).")
+        if not current_token.refresh_token:
+            exit_error("No refresh token available for this session.")
+        raw_token = current_token.refresh_token
+    else:
+        raw_token = current_token.access_token
+
+    # Handle --decode
+    if decode:
+        decoded = _decode_jwt(raw_token)
+        if decoded is None:
+            exit_error("Token is not a valid JWT format.")
+        jwt_header, jwt_payload = decoded
+        output = _format_decoded(jwt_header, jwt_payload, as_json=as_json)
+        if as_json:
+            print(output)
+        else:
+            console.print(output)
+        return
+
+    # Format output for raw token
+    if header:
+        token_type = (
+            current_token.token_type.value
+            if hasattr(current_token.token_type, "value")
+            else str(current_token.token_type)
+        )
+        output = f"{token_type} {raw_token}"
+    else:
+        output = raw_token
+
+    if copy:
+        try:
+            import pyperclip  # type: ignore[import-untyped]
+
+            pyperclip.copy(output)
+            console.print(f"[green]Token copied to clipboard ({provider_name}).[/]")
+        except ImportError:
+            exit_error("Clipboard support requires pyperclip.\nInstall with: pip install pyperclip")
+        except Exception as e:  # pylint: disable=broad-exception-caught
+            exit_error(f"Failed to copy to clipboard: {e}")
+    else:
+        # Print raw token (no Rich formatting for easy piping)
+        print(output)
+
+
+__all__ = ["token"]