kx-auth-cli 0.5.0__py3-none-any.whl

kx_auth_cli/discovery.py

@@ -0,0 +1,261 @@
+"""OAuth discovery + device-code primitives for ``kx auth login`` (stdlib + httpx, fastmcp-free).
+
+The mediation model is fixed by the MCP spec: the caller points at an endpoint it already knows —
+**the MCP server (the resource server)** — and that endpoint advertises its authorization server, so
+no realm, client-id or AS URL is ever hand-configured. The flow is:
+
+1. **RFC 9728** — GET the protected-resource metadata → ``authorization_servers``. The path-aware
+   form the RFC specifies is tried first (``/.well-known/oauth-protected-resource/<path>`` for a
+   server mounted under a path), falling back to the origin-root form.
+2. **RFC 8414 / OIDC** — GET the AS's ``.well-known`` metadata → device + token (+ registration)
+   endpoints.
+3. **RFC 7591 (optional)** — Dynamic Client Registration when the AS advertises a
+   ``registration_endpoint`` and no ``--client-id`` was given (the spec's "user never hand-configures
+   a client-id" ideal).
+4. **RFC 8628** — device-authorization request, then poll the token endpoint.
+
+After discovery the client talks **directly to the authorization server** — never back through the
+resource server, which the spec forbids from passing the token through. Errors carry a ``reason``
+code so the command layer can map them to the stable exit-code contract.
+"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass
+from typing import Any, Callable, Optional
+from urllib.parse import urljoin, urlsplit, urlunsplit
+
+import httpx
+
+
+class DiscoveryError(Exception):
+    """RFC 9728/8414 discovery failed (no metadata, no AS, no required endpoint)."""
+
+
+class DeviceAuthError(Exception):
+    """The device-code flow failed. ``reason`` is the OAuth error code (or a synthetic one).
+
+    Reasons the command layer maps to exit codes: ``access_denied`` → 4 (denied);
+    ``expired_token`` / ``timeout`` → 3 (auth-required); everything else → 1 (error).
+    """
+
+    def __init__(self, message: str, *, reason: str = "error") -> None:
+        super().__init__(message)
+        self.reason = reason
+
+
+@dataclass
+class AuthMetadata:
+    """The authorization-server endpoints `login` needs, resolved from discovery."""
+
+    authorization_server: str
+    token_endpoint: str
+    device_authorization_endpoint: Optional[str] = None
+    registration_endpoint: Optional[str] = None
+
+
+def _checked_url(value: Any, what: str, *, optional: bool = False) -> Optional[str]:
+    """Reject a URL httpx cannot parse as a DiscoveryError rather than a raw exception.
+
+    Most URLs here arrive from a *remote* metadata document, so a broken or hostile server must not be
+    able to crash the CLI. ``httpx.InvalidURL`` does not subclass ``httpx.HTTPError`` and
+    ``urlsplit``/``urljoin`` raise a bare ``ValueError``, so without this a malformed URL escapes the
+    module uncaught — a traceback instead of the command layer's exit-code contract. The type check is
+    part of that: remote JSON can hold anything, and a non-string would reach ``.rstrip``/``httpx``
+    as an ``AttributeError``. ``optional`` permits an absent endpoint, which is not a malformed one.
+    """
+    if value is None and optional:
+        return None
+    if not isinstance(value, str):
+        raise DiscoveryError(f"{what} was not a URL string: {value!r}")
+    try:
+        httpx.URL(value)
+    except (httpx.InvalidURL, ValueError) as exc:
+        raise DiscoveryError(f"{what} is not a usable URL ({value!r}): {exc}") from exc
+    return value
+
+
+def _prm_candidates(server: str) -> list[str]:
+    """RFC 9728 well-known URLs for a resource: the path-aware form first, then the origin root."""
+    try:
+        parts = urlsplit(server)
+    except ValueError as exc:  # e.g. a malformed IPv6-shaped host — stdlib raises, httpx never sees it
+        raise DiscoveryError(f"--server is not a usable URL ({server!r}): {exc}") from exc
+    origin = urlunsplit((parts.scheme, parts.netloc, "", "", ""))
+    root = origin + "/.well-known/oauth-protected-resource"
+    path = parts.path.strip("/")
+    return [f"{root}/{path}", root] if path else [root]
+
+
+def _get_json(client: httpx.Client, url: str) -> dict[str, Any]:
+    resp = client.get(url, headers={"Accept": "application/json"})
+    resp.raise_for_status()
+    try:
+        body = resp.json()
+    except ValueError as exc:
+        raise DiscoveryError(f"metadata at {url} was not valid JSON") from exc
+    if not isinstance(body, dict):
+        raise DiscoveryError(f"metadata at {url} was not a JSON object")
+    return body
+
+
+def discover(server: str, *, client: httpx.Client) -> AuthMetadata:
+    """Resolve the AS endpoints for an MCP-server (resource) URL via RFC 9728 → RFC 8414/OIDC."""
+    prm: Optional[dict[str, Any]] = None
+    last_prm_exc: Optional[Exception] = None
+    for prm_url in _prm_candidates(server):
+        try:
+            candidate = _get_json(client, prm_url)
+        except (httpx.HTTPError, httpx.InvalidURL, DiscoveryError) as exc:
+            last_prm_exc = exc
+            continue
+        if candidate.get("authorization_servers"):
+            prm = candidate
+            break
+        last_prm_exc = DiscoveryError(
+            f"{prm_url} advertised no authorization_servers — cannot discover an IdP"
+        )
+    if prm is None:
+        raise DiscoveryError(
+            f"could not discover protected-resource metadata for {server}: {last_prm_exc}"
+        )
+    as_url = _checked_url(prm["authorization_servers"][0], f"{server}'s advertised authorization server")
+
+    # RFC 8414 and OIDC differ in well-known path; try both against the AS origin + issuer path.
+    candidates = [
+        urljoin(as_url.rstrip("/") + "/", ".well-known/oauth-authorization-server"),
+        urljoin(as_url.rstrip("/") + "/", ".well-known/openid-configuration"),
+    ]
+    last_exc: Optional[Exception] = None
+    for url in candidates:
+        try:
+            meta = _get_json(client, url)
+        except (httpx.HTTPError, httpx.InvalidURL, DiscoveryError) as exc:
+            last_exc = exc
+            continue
+        token_endpoint = meta.get("token_endpoint")
+        if not token_endpoint:
+            last_exc = DiscoveryError(f"{url} advertised no token_endpoint")
+            continue
+        return AuthMetadata(
+            authorization_server=as_url,
+            token_endpoint=_checked_url(token_endpoint, f"{url}'s token_endpoint"),
+            device_authorization_endpoint=_checked_url(
+                meta.get("device_authorization_endpoint"),
+                f"{url}'s device_authorization_endpoint",
+                optional=True,
+            ),
+            registration_endpoint=_checked_url(
+                meta.get("registration_endpoint"), f"{url}'s registration_endpoint", optional=True
+            ),
+        )
+    raise DiscoveryError(
+        f"could not fetch authorization-server metadata from {as_url}: {last_exc}"
+    )
+
+
+def register_client(
+    meta: AuthMetadata, *, client: httpx.Client, client_name: str, scopes: Optional[list[str]] = None
+) -> str:
+    """RFC 7591 Dynamic Client Registration for the device-code flow → the issued ``client_id``."""
+    if not meta.registration_endpoint:
+        raise DiscoveryError(
+            "the authorization server advertises no registration_endpoint — pass --client-id "
+            "(or $KX_AUTH_CLIENT_ID) instead"
+        )
+    payload: dict[str, Any] = {
+        "client_name": client_name,
+        "grant_types": ["urn:ietf:params:oauth:grant-type:device_code"],
+        "token_endpoint_auth_method": "none",  # public client — device-code, no secret
+    }
+    if scopes:
+        payload["scope"] = " ".join(scopes)
+    try:
+        resp = client.post(meta.registration_endpoint, json=payload)
+        resp.raise_for_status()
+        body = resp.json()
+    except (httpx.HTTPError, ValueError) as exc:  # ValueError: a non-JSON body
+        raise DiscoveryError(f"dynamic client registration failed: {exc}") from exc
+    client_id = body.get("client_id")
+    if not client_id:
+        raise DiscoveryError("registration endpoint returned no client_id")
+    return client_id
+
+
+def start_device_authorization(
+    meta: AuthMetadata, client_id: str, *, client: httpx.Client, scopes: Optional[list[str]] = None
+) -> dict[str, Any]:
+    """RFC 8628 device-authorization request → the device/user codes + polling parameters."""
+    if not meta.device_authorization_endpoint:
+        raise DeviceAuthError(
+            "the authorization server advertises no device_authorization_endpoint — "
+            "device-code login is unavailable",
+            reason="device_flow_unsupported",
+        )
+    data = {"client_id": client_id}
+    if scopes:
+        data["scope"] = " ".join(scopes)
+    try:
+        resp = client.post(meta.device_authorization_endpoint, data=data)
+        resp.raise_for_status()
+        body = resp.json()
+    except (httpx.HTTPError, ValueError) as exc:  # ValueError: a non-JSON body
+        raise DeviceAuthError(f"device-authorization request failed: {exc}") from exc
+    if not body.get("device_code") or not body.get("user_code"):
+        raise DeviceAuthError("device-authorization response missing device_code/user_code")
+    return body
+
+
+def poll_for_token(
+    meta: AuthMetadata,
+    client_id: str,
+    device_code: str,
+    *,
+    client: httpx.Client,
+    interval: int = 5,
+    expires_in: int = 600,
+    sleep: Callable[[float], None] = time.sleep,
+    monotonic: Callable[[], float] = time.monotonic,
+) -> dict[str, Any]:
+    """RFC 8628 polling: hit the token endpoint until success, denial, or expiry.
+
+    ``sleep`` / ``monotonic`` are injectable so tests drive the loop without real waits.
+    """
+    deadline = monotonic() + expires_in
+    wait = max(1, interval)
+    while True:
+        resp = client.post(
+            meta.token_endpoint,
+            data={
+                "grant_type": "urn:ietf:params:oauth:grant-type:device_code",
+                "device_code": device_code,
+                "client_id": client_id,
+            },
+        )
+        try:
+            body: dict[str, Any] = resp.json() if resp.content else {}
+        except ValueError:
+            # A non-JSON body (e.g. a proxy's HTML error page) → fall through to the status-code
+            # error below rather than crashing out of the exit-code contract.
+            body = {}
+        if resp.status_code == 200 and body.get("access_token"):
+            return body
+
+        error = body.get("error", "")
+        if error == "authorization_pending":
+            pass
+        elif error == "slow_down":
+            wait += 5
+        elif error == "access_denied":
+            raise DeviceAuthError("the user denied the authorization request", reason="access_denied")
+        elif error == "expired_token":
+            raise DeviceAuthError("the device code expired before approval", reason="expired_token")
+        else:
+            raise DeviceAuthError(
+                f"token endpoint returned an unexpected error: {error or resp.status_code}"
+            )
+
+        if monotonic() >= deadline:
+            raise DeviceAuthError("timed out waiting for device-code approval", reason="timeout")
+        sleep(wait)

kx_auth_cli/envelope.py

@@ -0,0 +1,145 @@
+"""The one output boundary every ``kx`` command runs behind.
+
+The published contract (public/CLAUDE.md, docs/KX_AUTH_CLI.md): every command supports ``--json`` and
+prints exactly one envelope on stdout --
+
+    {"status": "ok",     "result": {...}}                       success
+    {"status": <status>, "reason": "..."}                       failure
+    {"status": "denied", "result": {...}}                       a refusal that carries the decision it made
+    {"status": "error",  "result": {...}, "reason": "..."}      ``rbac verify --fail-on``: worked, but unacceptable
+
+-- with ``status`` in ``ok | error | auth_required | denied`` and the exit code ``0`` ok, ``1`` error,
+``2`` usage, ``3`` auth-required, ``4`` denied. Without ``--json`` a success prints the result as JSON
+(or ``ok`` when there is nothing to return) to stdout and a failure prints ``<status>: <reason>`` to
+stderr, so stdout is parseable either way. ``"error"`` is the status for BOTH exit 1 and exit 2: the
+code, not the text, is what a caller branches on.
+
+A command expresses an outcome by returning its result or raising a :class:`CliError`; :func:`guarded`
+turns either into the envelope and the exit code. Nothing else in the package prints an envelope and no
+command holds its own exit constants, so a new command cannot get the contract wrong by construction.
+Stdlib only, so the base install stays fastmcp-free.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from typing import Any, Callable
+
+EXIT_OK = 0
+EXIT_ERROR = 1
+EXIT_USAGE = 2
+EXIT_AUTH_REQUIRED = 3
+EXIT_DENIED = 4
+
+
+class CliError(Exception):
+    """A failure the command has classified. The base class IS the operational error (exit 1).
+
+    ``result`` lets a refusal carry the decision it made: ``rbac check`` answers a denial with the
+    engine's own ``{"allowed": false, ...}`` and ``verify --fail-on`` fails a pipeline while still
+    reporting its findings, so the envelope loses nothing a caller could act on.
+    """
+
+    status = "error"
+    exit_code = EXIT_ERROR
+
+    def __init__(self, reason: str | None = None, *, result: Any = None) -> None:
+        # Exception(None) stringifies as "None"; a reason-less refusal must read as "" instead.
+        super().__init__(*(() if reason is None else (reason,)))
+        self.reason = reason
+        self.result = result
+
+
+class UsageError(CliError):
+    """A value the CALLER typed is unusable (exit 2). Same "error" status as an operational failure:
+    the envelope does not distinguish the two, the exit code does. Deliberately NOT a ValueError, so
+    "usage" can only ever come from a site that classified it as such — a bare ValueError from a
+    dependency (the outbound seam raises one for a misconfiguration) is an operational error."""
+
+    exit_code = EXIT_USAGE
+
+
+class AuthRequired(CliError):
+    """No usable credential, or an expired one (exit 3)."""
+
+    status = "auth_required"
+    exit_code = EXIT_AUTH_REQUIRED
+
+
+class Denied(CliError):
+    """A valid caller was refused by policy (exit 4)."""
+
+    status = "denied"
+    exit_code = EXIT_DENIED
+
+
+def json_parent() -> argparse.ArgumentParser:
+    """The single ``--json`` declaration; every leaf parser takes it via ``parents=``."""
+    parent = argparse.ArgumentParser(add_help=False)
+    parent.add_argument("--json", action="store_true", help="Emit the stable JSON envelope (the agent path).")
+    return parent
+
+
+def note(text: str) -> None:
+    """An advisory for a human (a shadowed $KX_AUTH_TOKEN, login's device-code prompt). Always stderr,
+    so a ``--json`` stdout stays exactly one envelope."""
+    print(text, file=sys.stderr)
+
+
+def emit(
+    args: argparse.Namespace,
+    status: str,
+    *,
+    result: Any = None,
+    reason: str | None = None,
+    human: Callable[[Any], str] | None = None,
+) -> None:
+    """Print the one envelope (``--json``) or its human rendering.
+
+    ``human`` renders a SUCCESS for a terminal; the default is the result as JSON. A command supplies
+    one when the bare result is the wrong thing to show a terminal: ``exchange``'s result holds a
+    bearer that must not reach a CI log or a shell history file.
+    """
+    if args.json:
+        envelope: dict[str, Any] = {"status": status}
+        if result is not None:
+            envelope["result"] = result
+        if reason is not None:
+            envelope["reason"] = reason
+        print(json.dumps(envelope, indent=2, default=str))
+    elif status == "ok":
+        if human is not None:
+            print(human(result))
+        elif result is not None:
+            print(json.dumps(result, indent=2, default=str))
+        else:
+            print("ok")
+    else:
+        print(status if reason is None else f"{status}: {reason}", file=sys.stderr)
+
+
+def guarded(
+    args: argparse.Namespace,
+    fn: Callable[[], Any],
+    *,
+    human: Callable[[Any], str] | None = None,
+) -> int:
+    """Run one command body and own its envelope and exit code.
+
+    ``fn`` returns the success result (``None`` for a bare ``ok``) or raises a :class:`CliError`.
+    Anything else it raises is an operational error: the contract is one envelope and a documented
+    code, never a traceback, so the residue lands here rather than in ``cli.main``, which cannot know a
+    command's shape or code.
+    """
+    try:
+        result = fn()
+    except CliError as exc:
+        emit(args, exc.status, result=exc.result, reason=exc.reason)
+        return exc.exit_code
+    except Exception as exc:  # noqa: BLE001 -- the boundary is the point
+        emit(args, "error", reason=f"{type(exc).__name__}: {exc}")
+        return EXIT_ERROR
+    emit(args, "ok", result=result, human=human)
+    return EXIT_OK

kx_auth_cli/exchange.py

@@ -0,0 +1,212 @@
+"""``kx auth exchange`` — swap a subject token for a backend-scoped credential (RFC 8693 from a shell).
+
+A thin wrapper over the shared :func:`kx_auth_core.exchange` seam — the *same* outbound code path a
+KX MCP server's backends use — so the wire shape and audit chain are one implementation. Default strategy
+is ``rfc_8693`` (the workload-identity bootstrap target: ``kubectl create token`` / ``gh
+actions-token`` → ``kx auth exchange`` → backend-scoped token); ``passthrough`` / ``service_account``
+/ custom registered strategies are selectable too.
+
+Subject-token source, in order of **explicitness** (see ``_resolve_subject``): ``--subject`` → piped
+stdin → ``$KX_AUTH_TOKEN`` → the cached ``login`` token for ``--server`` (the seamless ``login`` →
+``exchange`` chain). ``service_account`` needs no subject. Maps the seam's result to the stable exit-code contract: ``0`` ok · ``1`` error ·
+``2`` usage · ``3`` auth-required (the only subject candidate was an expired ``login`` cache entry) ·
+``4`` denied (a ``passthrough`` audience-guard refusal).
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import os
+import sys
+import time
+
+from kx_auth_core import OutboundConfig, exchange, outbound_strategies
+
+from . import cache
+from .envelope import AuthRequired, CliError, Denied, UsageError, guarded, note
+
+_NEEDS_SUBJECT = {"passthrough", "rfc_8693"}
+
+HELP_DESCRIPTION = (
+    "Exchange a subject token for a backend-scoped credential via the shared outbound seam "
+    "(one implementation, shared with the server side). Default strategy: rfc_8693."
+)
+HELP_EPILOG = """\
+exit codes (branch on the code, not the text):
+  0  ok             a credential was minted/forwarded
+  1  error          misconfig, unreachable endpoint, or the endpoint returned no token
+  2  usage          bad flags, an unrecognised --strategy, or no subject token for one that needs it
+  3  auth-required  the cached login for --server has expired — `kx auth login` again
+  4  denied         the strategy refused (e.g. passthrough audience-guard mismatch)
+
+subject source, most explicit first:  --subject  ->  piped stdin  ->  $KX_AUTH_TOKEN  ->  login cache (--server)
+  a pipe outranks $KX_AUTH_TOKEN, so a leftover token cannot shadow one you piped in; when both are
+  present the pipe is used and a note is written to stderr
+
+strategies:
+  rfc_8693         (default) token exchange at --token-url for --audience; needs a subject token
+  passthrough      forward the subject unchanged iff its aud already includes --audience
+  service_account  client_credentials at --token-url (the caller's own identity; no subject)
+
+examples:
+  # RFC 8693 swap (subject as a flag), structured output
+  kx auth exchange --subject "$TOK" --audience kdbai \\
+    --token-url https://idp/token --client-id mcp-container --client-secret "$SECRET" --json
+
+  # chain off a prior `kx auth login` — subject pulled from the cache for that server
+  kx auth login --server https://mcp.example --json
+  kx auth exchange --server https://mcp.example --audience backend-api --token-url https://idp/token --json
+"""
+
+
+def add_arguments(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--subject", help="The subject (inbound) token. Falls back to piped stdin, then $KX_AUTH_TOKEN, then the login cache.")
+    parser.add_argument("--audience", help="Target backend audience (the token is scoped to this).")
+    parser.add_argument("--strategy", default="rfc_8693", help="Outbound strategy (default rfc_8693).")
+    parser.add_argument("--token-url", help="OIDC/STS token endpoint (rfc_8693 / service_account).")
+    parser.add_argument("--resource", help="RFC 8707 resource URI — an alternative to --audience.")
+    parser.add_argument("--client-id", help="Client id for authenticating at the token endpoint.")
+    parser.add_argument(
+        "--client-secret",
+        default=os.environ.get("KX_AUTH_CLIENT_SECRET"),
+        help="Client secret paired with --client-id. Falls back to $KX_AUTH_CLIENT_SECRET "
+        "(preferred — keeps the secret out of shell history and process listings).",
+    )
+    parser.add_argument(
+        "--client-auth", choices=("post", "basic"), default="post",
+        help="How client credentials reach the token endpoint (default post).",
+    )
+    parser.add_argument(
+        "--scope", action="append", metavar="SCOPE",
+        help="Requested scope; repeatable, or comma/space-separated within one value.",
+    )
+    parser.add_argument("--server", help="MCP-server URL — used to pull the subject from the login cache.")
+    parser.add_argument("--no-verify", action="store_true", help="Disable TLS verification (dev IdPs).")
+    parser.add_argument("--timeout", type=float, default=30.0, help="Token-request timeout, seconds.")
+
+
+def _resolve_subject(args: argparse.Namespace) -> tuple[str | None, bool]:
+    """Resolve the subject token; the second element flags that the only candidate was an
+    expired ``login``-cache entry (so the caller can map it to auth-required, not usage).
+
+    Precedence is by **explicitness**, not convenience: an explicit flag, then input piped at *this*
+    invocation, then the ambient environment, then the cache.
+
+    ``$KX_AUTH_TOKEN`` deliberately ranks **below** stdin. It is inherited state — very often left over
+    from an earlier ``kx auth login``, or from the `exchange` → `assert` handoff itself — and while it
+    outranked a piped token, the workload-identity path (`platform token | kx auth exchange`) silently
+    exchanged the stale credential instead of the one it was handed. Wrong identity, no error. Ambient
+    state must never win over an argument the caller passed on purpose.
+    """
+    if args.subject:
+        return args.subject, False
+
+    # isatty() keeps an interactive run from blocking on a terminal. A non-tty stdin carrying nothing
+    # reads as "" (or raises) and falls through to the environment. A caller who inherits an open, idle
+    # stdin blocks here — inherent to accepting piped input, and no worse than before this reordering,
+    # which only changes WHICH source wins once stdin has actually yielded something.
+    piped: str | None = None
+    try:
+        if not sys.stdin.isatty():
+            piped = sys.stdin.read().strip() or None
+    except (OSError, ValueError):
+        piped = None
+
+    env = (os.environ.get("KX_AUTH_TOKEN") or "").strip() or None
+
+    if piped:
+        # Say so rather than resolving the ambiguity silently — on stderr, so a --json envelope on
+        # stdout stays machine-parseable (the same split `login` uses for its device-code prompt).
+        if env and env != piped:
+            note(
+                "note: using the piped subject token; $KX_AUTH_TOKEN is also set and was ignored. "
+                "Pass --subject to be explicit."
+            )
+        return piped, False
+    if env:
+        return env, False
+
+    if args.server:
+        entry = cache.get(args.server)
+        if entry and entry.get("access_token"):
+            expires_at = entry.get("expires_at")
+            if expires_at:
+                try:
+                    expired = time.time() >= float(expires_at)
+                except (TypeError, ValueError):
+                    # An expiry that will not read is not a usable credential: report it as
+                    # auth-required rather than sending a token whose lifetime is unknown.
+                    return None, True
+                if expired:
+                    return None, True
+            return entry["access_token"], False
+    return None, False
+
+
+def _scopes(args: argparse.Namespace) -> list[str] | None:
+    if not args.scope:
+        return None
+    out: list[str] = []
+    for chunk in args.scope:
+        out.extend(part for part in chunk.replace(",", " ").split() if part)
+    return out or None
+
+
+def _config_from_args(args: argparse.Namespace) -> OutboundConfig:
+    return OutboundConfig(
+        strategy=args.strategy,
+        token_url=args.token_url,
+        audience=args.audience,
+        resource=args.resource,
+        client_id=args.client_id,
+        client_secret=args.client_secret,
+        client_auth=args.client_auth,
+        scopes=_scopes(args),
+        verify=not args.no_verify,
+        timeout=args.timeout,
+    )
+
+
+def _human(result: dict) -> str:
+    # No access_token here: this line goes to a terminal, a CI log and a shell history file. Anyone who
+    # needs the token itself is already using --json.
+    return f"ok — strategy={result['strategy']} token_type={result['token_type']} expires_in={result['expires_in']}"
+
+
+def run(args: argparse.Namespace) -> int:
+    def fn() -> dict:
+        # Checked against the registry, never restated here: a typo like "rfc8693" is not in
+        # `_NEEDS_SUBJECT` either, so without this it would skip the subject check below and surface as
+        # a generic exit-1 failure deep in the outbound seam instead of a usage error naming the typo.
+        known = outbound_strategies()
+        if args.strategy not in known:
+            raise UsageError(f"unknown --strategy {args.strategy!r}; choose one of: {', '.join(sorted(known))}")
+
+        subject, cache_expired = _resolve_subject(args)
+        if args.strategy in _NEEDS_SUBJECT and not subject:
+            if cache_expired:
+                raise AuthRequired(
+                    f"the cached login for {args.server} has expired — "
+                    f"run `kx auth login --server {args.server}` again"
+                )
+            raise UsageError(
+                f"strategy '{args.strategy}' needs a subject token "
+                "(pass --subject, $KX_AUTH_TOKEN, stdin, or --server for the login cache)"
+            )
+
+        try:
+            credential = asyncio.run(exchange(_config_from_args(args), subject))
+        except PermissionError as exc:  # strategy refusal (e.g. passthrough audience guard)
+            raise Denied(str(exc)) from exc
+        except Exception as exc:  # the seam's ValueError (misconfig / no token), httpx, unexpected
+            raise CliError(str(exc)) from exc
+        return {
+            "access_token": credential.access_token,
+            "token_type": credential.token_type,
+            "expires_in": credential.expires_in,
+            "strategy": credential.strategy,
+            "claims": credential.claims,
+        }
+
+    return guarded(args, fn, human=_human)