cli: add auth status

provide status of the current session:
Token expiry: 2026-01-06 19:39:42
Status: Valid (9h 17m remaining)
Subject: ...
Issuer: https://...

Signed-off-by: Benny Zlotnik <bzlotnik@redhat.com>

Author: bennyz

packages/jumpstarter-cli-common/jumpstarter_cli_common/oidc.py

@@ -1,5 +1,6 @@
 import json
 import os
+import time
 from dataclasses import dataclass
 from functools import wraps
 from typing import ClassVar
@@ -23,7 +24,8 @@ def opt_oidc(f):
     @click.option("--username", help="OIDC username")
     @click.option("--password", help="OIDC password")
     @click.option("--connector-id", "connector_id", help="OIDC token exchange connector id (Dex specific)")
-    @click.option("--callback-port",
+    @click.option(
+        "--callback-port",
         "callback_port",
         type=click.IntRange(0, 65535),
         default=None,
@@ -93,7 +95,7 @@ async def authorization_code_grant(self, callback_port: int | None = None):
             elif env_value.isdigit() and int(env_value) <= 65535:
                 port = int(env_value)
             else:
-                raise click.ClickException(f"Invalid {JMP_OIDC_CALLBACK_PORT} \"{env_value}\": must be a valid port")
+                raise click.ClickException(f'Invalid {JMP_OIDC_CALLBACK_PORT} "{env_value}": must be a valid port')
 
         tx, rx = create_memory_object_stream()
 
@@ -133,8 +135,50 @@ async def callback(request):
 
 
 def decode_jwt(token: str):
-    return json.loads(extract_compact(token.encode()).payload)
+    try:
+        return json.loads(extract_compact(token.encode()).payload)
+    except (ValueError, KeyError, TypeError) as e:
+        raise ValueError(f"Invalid JWT format: {e}") from e
 
 
 def decode_jwt_issuer(token: str):
     return decode_jwt(token).get("iss")
+
+
+def get_token_expiry(token: str) -> int | None:
+    """Get token expiry timestamp (Unix epoch seconds) from JWT.
+
+    Returns None if token doesn't have an exp claim.
+    """
+    return decode_jwt(token).get("exp")
+
+
+def get_token_remaining_seconds(token: str) -> float | None:
+    """Get seconds remaining until token expires.
+
+    Returns:
+        Positive value if token is still valid
+        Negative value if token is expired (magnitude = how long ago)
+        None if token doesn't have an exp claim
+    """
+    exp = get_token_expiry(token)
+    if exp is None:
+        return None
+    return exp - time.time()
+
+
+def is_token_expired(token: str, buffer_seconds: int = 0) -> bool:
+    """Check if token is expired or will expire within buffer_seconds.
+
+    Args:
+        token: JWT token string
+        buffer_seconds: Consider expired if less than this many seconds remain
+
+    Returns:
+        True if token is expired or will expire within buffer
+        False if token is still valid (or has no exp claim)
+    """
+    remaining = get_token_remaining_seconds(token)
+    if remaining is None:
+        return False
+    return remaining < buffer_seconds

packages/jumpstarter-cli/jumpstarter_cli/auth.py

@@ -0,0 +1,66 @@
+import time
+from datetime import datetime, timezone
+
+import click
+from jumpstarter_cli_common.config import opt_config
+from jumpstarter_cli_common.oidc import decode_jwt
+
+
+@click.group()
+def auth():
+    """
+    Authentication and token management commands
+    """
+
+
+@auth.command(name="status")
+@opt_config(exporter=False)
+def token_status(config):
+    """
+    Display token status and expiry information
+    """
+    token_str = getattr(config, "token", None)
+
+    if not token_str:
+        click.echo(click.style("No token found in config", fg="yellow"))
+        return
+
+    try:
+        payload = decode_jwt(token_str)
+    except Exception as e:
+        click.echo(click.style(f"Failed to decode token: {e}", fg="red"))
+        return
+
+    exp = payload.get("exp")
+    if not exp:
+        click.echo(click.style("Token has no expiry claim", fg="yellow"))
+        return
+
+    remaining = exp - time.time()
+    exp_dt = datetime.fromtimestamp(exp, tz=timezone.utc)
+
+    click.echo(f"Token expiry: {exp_dt.strftime('%Y-%m-%d %H:%M:%S')}")
+
+    if remaining < 0:
+        hours = int(abs(remaining) / 3600)
+        mins = int((abs(remaining) % 3600) / 60)
+        click.echo(click.style(f"Status: EXPIRED ({hours}h {mins}m ago)", fg="red", bold=True))
+        click.echo(click.style("Run 'jmp login' to refresh your credentials.", fg="yellow"))
+    elif remaining < 300:  # Less than 5 minutes
+        mins = int(remaining / 60)
+        secs = int(remaining % 60)
+        click.echo(click.style(f"Status: EXPIRING SOON ({mins}m {secs}s remaining)", fg="red", bold=True))
+        click.echo(click.style("Run 'jmp login' to refresh your credentials.", fg="yellow"))
+    elif remaining < 3600:  # Less than 1 hour
+        mins = int(remaining / 60)
+        click.echo(click.style(f"Status: Valid ({mins}m remaining)", fg="yellow"))
+    else:
+        hours = int(remaining / 3600)
+        mins = int((remaining % 3600) / 60)
+        click.echo(click.style(f"Status: Valid ({hours}h {mins}m remaining)", fg="green"))
+
+    # Show additional token info
+    if payload.get("sub"):
+        click.echo(f"Subject: {payload.get('sub')}")
+    if payload.get("iss"):
+        click.echo(f"Issuer: {payload.get('iss')}")

packages/jumpstarter-cli/jumpstarter_cli/jmp.py

@@ -5,6 +5,7 @@
 from jumpstarter_cli_common.version import version
 from jumpstarter_cli_driver import driver
 
+from .auth import auth
 from .config import config
 from .create import create
 from .delete import delete
@@ -21,6 +22,7 @@ def jmp():
     """The Jumpstarter CLI"""
 
 
+jmp.add_command(auth)
 jmp.add_command(create)
 jmp.add_command(delete)
 jmp.add_command(update)