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

kx_auth_cli/introspect.py

@@ -0,0 +1,162 @@
+"""``kx auth introspect`` — decode/validate a bearer against the configured ``KX_MCP_AUTH`` keys.
+
+Reuses the shared :func:`kx_auth_core.verify_token` — the same validation a KX MCP server enforces on
+the way in, so a verdict here is the verdict there — and maps its categorised verdict to the stable
+exit-code contract:
+
+* ``0`` valid · ``1`` error (malformed / bad signature / unreachable JWKS) · ``2`` usage (no token) ·
+  ``3`` auth-required (expired — the agent should ``login``) · ``4`` denied (issuer / audience /
+  required-scope mismatch).
+
+Config defaults come from the ``KX_MCP_AUTH*`` environment — the same variables a KX MCP server
+reads, so pointing both at one environment checks against one set of keys; the flags below override
+per-invocation. ``introspect`` is stateless — it does not touch the token cache. (Server-advertised
+RFC 9728 discovery is handled by ``login``.)
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+
+from kx_auth_core import AUTH_REQUIRED, DENIED, AuthSettings, verify_token
+
+from .envelope import AuthRequired, CliError, Denied, UsageError, guarded, note
+
+# CLI help kept separate from the module docstring above: the docstring is RST for code/IDE readers;
+# this is clean plaintext for the terminal (and for an agent reading `--help`). RawDescriptionHelpFormatter
+# prints the epilog verbatim, so the alignment below is preserved.
+HELP_DESCRIPTION = (
+    "Validate a bearer token against the same keys a KX MCP server enforces and report a "
+    "machine-readable verdict. Stateless — does not touch any token cache."
+)
+HELP_EPILOG = """\
+exit codes (branch on the code, not the text):
+  0  ok             valid
+  1  error          malformed / bad signature / unreachable JWKS
+  2  usage          bad flags, or no token supplied
+  3  auth-required  well-signed but expired — re-authenticate (kx auth login)
+  4  denied         well-signed but wrong issuer / audience / required scope
+
+token source, most explicit first:  argument  ->  piped stdin  ->  $KX_AUTH_TOKEN
+  a pipe outranks $KX_AUTH_TOKEN (same rule as `exchange`); when both are set the pipe is used and a
+  note is written to stderr
+
+config comes from the environment (the same vars the container reads); flags override per call:
+  --public-key-path   KX_MCP_AUTH_PUBLIC_KEY_PATH   static mode (PEM on disk)
+  --public-key        KX_MCP_AUTH_PUBLIC_KEY        static mode (inline PEM)
+  --jwks-uri          KX_MCP_AUTH_JWKS_URI          jwks mode (remote endpoint)
+  --issuer            KX_MCP_AUTH_ISSUER
+  --audience          KX_MCP_AUTH_AUDIENCE
+  --algorithm         KX_MCP_AUTH_ALGORITHM         default RS256
+  --required-scopes   KX_MCP_AUTH_REQUIRED_SCOPES   comma/space separated
+
+examples:
+  # token + key as flags, structured verdict
+  kx auth introspect "$TOKEN" --public-key-path key.pub --issuer https://idp --audience my-api --json
+
+  # config + token entirely from the environment (matches the container)
+  KX_MCP_AUTH=static KX_MCP_AUTH_PUBLIC_KEY_PATH=key.pub \\
+    KX_AUTH_TOKEN="$TOKEN" kx auth introspect --json
+
+  # validate against a live JWKS endpoint, token piped on stdin
+  echo "$TOKEN" | kx auth introspect --jwks-uri https://idp/.well-known/jwks.json
+"""
+
+# kx_auth_core's verdict categories, minus OK (a success) and ERROR (the default CliError).
+_FAILURES = {AUTH_REQUIRED: AuthRequired, DENIED: Denied}
+
+
+def add_arguments(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument(
+        "token",
+        nargs="?",
+        help="The bearer token to validate. Falls back to piped stdin, then $KX_AUTH_TOKEN.",
+    )
+    # Verification config — overrides the KX_MCP_AUTH* environment for this invocation.
+    parser.add_argument("--jwks-uri", help="Remote JWKS endpoint (selects jwks mode).")
+    parser.add_argument("--public-key", help="Inline RS256 public-key PEM (selects static mode).")
+    parser.add_argument(
+        "--public-key-path", help="Path to an RS256 public-key PEM (selects static mode)."
+    )
+    parser.add_argument("--issuer", help="Expected `iss` claim.")
+    parser.add_argument("--audience", help="Expected `aud` claim.")
+    parser.add_argument("--algorithm", help="Signing algorithm to accept (default RS256).")
+    parser.add_argument(
+        "--required-scopes", help="Comma/space-separated scopes that must be present."
+    )
+
+
+def _resolve_token(args: argparse.Namespace) -> str | None:
+    """Resolve the bearer to validate, in order of **explicitness**: argument → piped stdin →
+    ``$KX_AUTH_TOKEN``.
+
+    The environment ranks **below** a pipe, matching ``exchange``'s subject resolution — one rule across
+    the CLI, since an agent that learns one command's precedence will apply it to the other. It also
+    matters more here than it looks: ``introspect`` is the pre-flight ("does the token my gateway will
+    forward actually validate?"), so silently reporting a verdict about a *leftover* ``$KX_AUTH_TOKEN``
+    instead of the token piped in would answer a question nobody asked, and answer it convincingly.
+    """
+    if args.token:
+        return args.token
+
+    piped: str | None = None
+    try:
+        if not sys.stdin.isatty():
+            piped = sys.stdin.read().strip() or None
+    except (OSError, ValueError):
+        # stdin unavailable (e.g. captured under a test harness) — treat as "nothing piped".
+        piped = None
+
+    env = (os.environ.get("KX_AUTH_TOKEN") or "").strip() or None
+
+    if piped:
+        if env and env != piped:
+            note("note: validating the piped token; $KX_AUTH_TOKEN is also set and was ignored.")
+        return piped
+    return env
+
+
+def _settings_from_args(args: argparse.Namespace) -> AuthSettings:
+    """Start from the KX_MCP_AUTH* environment, then apply explicit flag overrides. Key material on
+    the CLI selects the mode, so `introspect <token> --public-key-path k.pub` works with no env."""
+    overrides: dict = {}
+    for flag in ("jwks_uri", "public_key", "public_key_path", "issuer", "audience"):
+        value = getattr(args, flag)
+        if value is not None:
+            overrides[flag] = value
+    if args.algorithm:
+        overrides["algorithm"] = args.algorithm
+    if args.required_scopes:
+        overrides["required_scopes"] = args.required_scopes
+    if args.public_key or args.public_key_path:
+        overrides["mode"] = "static"
+    elif args.jwks_uri:
+        overrides["mode"] = "jwks"
+    return AuthSettings(**overrides)
+
+
+def _human(result: dict) -> str:
+    return f"valid — client_id={result['client_id']} scopes={result['scopes'] or []}"
+
+
+def run(args: argparse.Namespace) -> int:
+    def fn() -> dict:
+        token = _resolve_token(args)
+        if not token:
+            raise UsageError("no token provided (pass as an argument, $KX_AUTH_TOKEN, or via stdin)")
+        try:
+            verdict = verify_token(token, _settings_from_args(args))
+        except Exception as exc:  # config / unexpected failure → error, with the message as it came
+            raise CliError(str(exc)) from exc
+        if not verdict.valid:
+            raise _FAILURES.get(verdict.category, CliError)(verdict.reason)
+        return {
+            "valid": True,
+            "client_id": verdict.client_id,
+            "scopes": verdict.scopes,
+            "claims": verdict.claims,
+        }
+
+    return guarded(args, fn, human=_human)

kx_auth_cli/login.py

@@ -0,0 +1,153 @@
+"""``kx auth login`` — acquire a bearer for an MCP server via server-advertised device-code OAuth.
+
+The mediation model the MCP spec mandates (see ``discovery``): point ``kx auth`` at the **MCP server
+(the resource server)** you connect to — *not* a backend. That server publishes RFC 9728 metadata
+naming its authorization server; ``kx auth`` discovers the AS and runs the **RFC 8628 device-code**
+flow directly against it (never redirecting through the resource server). The token is audienced to
+the MCP-server resource; backend-scoped tokens come from a separate ``kx auth exchange``.
+
+Client identity is **DCR-first**: when the AS advertises a ``registration_endpoint`` and no
+``--client-id`` is given, register dynamically (RFC 7591) so the user never hand-configures a
+client-id; ``--client-id`` / ``$KX_AUTH_CLIENT_ID`` overrides. The acquired credential is written to
+the endpoint-keyed token cache for ``kx auth exchange`` to chain off.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import time
+
+import httpx
+
+from . import cache, discovery
+from .discovery import DeviceAuthError, DiscoveryError
+from .envelope import AuthRequired, CliError, Denied, guarded, note
+
+# DeviceAuthError.reason → how the refusal is classified (anything unlisted is a plain error).
+_DEVICE_FAILURES = {
+    "access_denied": Denied,
+    "expired_token": AuthRequired,
+    "timeout": AuthRequired,
+}
+
+HELP_DESCRIPTION = (
+    "Acquire a bearer for an MCP server via the device-code flow against the authorization server "
+    "the server advertises (RFC 9728 discovery → RFC 8628). Caches the token for `exchange`."
+)
+HELP_EPILOG = """\
+exit codes (branch on the code, not the text):
+  0  ok             a token was acquired and cached
+  1  error          discovery failed, unreachable endpoint, no device-code support, or DCR failure
+  2  usage          bad flags
+  3  auth-required  the device code expired / timed out before approval — retry
+  4  denied         the user denied the authorization request
+
+--server is the MCP-server (resource) URL you connect to — NOT a backend. The client talks directly
+to the discovered authorization server; the token is audienced to that resource. Use `kx auth
+exchange` for backend-scoped tokens.
+
+client identity (DCR-first):  RFC 7591 dynamic registration if the AS supports it, else --client-id
+                              (or $KX_AUTH_CLIENT_ID).
+
+examples:
+  kx auth login --server https://mcp.example --json
+  kx auth login --server https://mcp.example --client-id my-public-client --scope "kdbx.read offline_access"
+"""
+
+
+def add_arguments(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--server", required=True, help="MCP-server (resource) URL to authenticate to.")
+    parser.add_argument("--client-id", help="OAuth client id (overrides DCR; falls back to $KX_AUTH_CLIENT_ID).")
+    parser.add_argument(
+        "--scope", action="append", metavar="SCOPE",
+        help="Requested scope; repeatable, or comma/space-separated within one value.",
+    )
+    parser.add_argument("--no-verify", action="store_true", help="Disable TLS verification (dev IdPs).")
+    parser.add_argument("--timeout", type=float, default=30.0, help="Per-request timeout, seconds.")
+
+
+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 _prompt(device: dict) -> None:
+    """Show the user where to approve — to stderr, so a --json stdout stays clean."""
+    complete = device.get("verification_uri_complete")
+    uri = device.get("verification_uri", "<unknown>")
+    code = device.get("user_code", "<unknown>")
+    if complete:
+        note(f"To authorize, open: {complete}")
+    note(f"To authorize, visit {uri} and enter code: {code}")
+
+
+def _acquire(args: argparse.Namespace) -> dict:
+    """The flow itself: discover, register, device-authorize, poll, cache. Returns the result."""
+    scopes = _scopes(args)
+    client_id = args.client_id or os.environ.get("KX_AUTH_CLIENT_ID")
+    with httpx.Client(verify=not args.no_verify, timeout=args.timeout) as client:
+        meta = discovery.discover(args.server, client=client)
+        if not client_id:
+            client_id = discovery.register_client(
+                meta, client=client, client_name="kx-auth-cli", scopes=scopes
+            )
+        device = discovery.start_device_authorization(meta, client_id, client=client, scopes=scopes)
+        _prompt(device)
+        token = discovery.poll_for_token(
+            meta,
+            client_id,
+            device["device_code"],
+            client=client,
+            interval=int(device.get("interval", 5)),
+            expires_in=int(device.get("expires_in", 600)),
+        )
+
+    expires_in = token.get("expires_in")
+    now = int(time.time())
+    credential = {
+        "access_token": token["access_token"],
+        "refresh_token": token.get("refresh_token"),
+        "token_type": token.get("token_type", "Bearer"),
+        "scope": token.get("scope"),
+        "expires_at": now + int(expires_in) if expires_in else None,
+        "issued_at": now,
+        "authorization_server": meta.authorization_server,
+    }
+    cache_path = cache.save(args.server, credential)
+    return {
+        "server": args.server,
+        "authorization_server": meta.authorization_server,
+        "access_token": token["access_token"],
+        "token_type": token.get("token_type", "Bearer"),
+        "expires_in": expires_in,
+        "cached": True,
+        "cache_path": str(cache_path),
+    }
+
+
+def _human(result: dict) -> str:
+    return f"ok — logged in to {result['server']} (cached at {result['cache_path']})"
+
+
+def run(args: argparse.Namespace) -> int:
+    def fn() -> dict:
+        try:
+            return _acquire(args)
+        except DiscoveryError as exc:
+            raise CliError(str(exc)) from exc
+        except DeviceAuthError as exc:
+            raise _DEVICE_FAILURES.get(exc.reason, CliError)(str(exc)) from exc
+        # httpx.InvalidURL does NOT subclass httpx.HTTPError. `discovery` rejects a malformed URL as
+        # a DiscoveryError before httpx sees it, but the exit-code contract is owned here, so this
+        # layer does not depend on that holding.
+        except (httpx.HTTPError, httpx.InvalidURL) as exc:
+            raise CliError(f"network error talking to the authorization server: {exc}") from exc
+        # Anything else — a token response missing `access_token`, a non-numeric `expires_in`, an
+        # unwritable cache — is the residue `guarded` files as an operational error.
+
+    return guarded(args, fn, human=_human)

kx_auth_cli/qbridge.py

@@ -0,0 +1,54 @@
+"""The two things every command that talks to q needs: a quiet PyKX import, and readable q values.
+
+Both exist only because of how PyKX presents itself and how q presents its values, so they live
+together rather than being restated by each command that connects.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import io
+from typing import Any
+
+
+def import_pykx() -> Any:
+    """Import PyKX without letting its banner reach stdout.
+
+    Community PyKX prints an embedded-q welcome banner while importing. Every command here has a
+    one-envelope stdout contract, so a library banner would corrupt `--json` output for a caller that
+    is parsing it — and it is irrelevant to a remote qIPC client in any case.
+
+    Raises whatever the import raised, so each caller can map it to its own error surface.
+    """
+    with contextlib.redirect_stdout(io.StringIO()):
+        import pykx as kx
+    return kx
+
+
+def readable(obj: Any) -> Any:
+    """Convert a q readback into something JSON can render honestly.
+
+    Three q-to-Python artifacts have to be undone, or they leak into an interface contract:
+
+    * a PyKX wrapper that has not been converted yet (`.py()`),
+    * q char vectors, which arrive as `bytes` and would print as `b'...'`,
+    * numpy scalars and arrays, which `json.dumps` cannot serialise.
+
+    Containers are walked so a nested claims blob comes back clean.
+    """
+    if hasattr(obj, "py"):
+        obj = obj.py()
+    if isinstance(obj, bytes):
+        return obj.decode("utf-8", "replace")
+    if isinstance(obj, dict):
+        return {readable(k): readable(v) for k, v in obj.items()}
+    if isinstance(obj, (list, tuple)):
+        return [readable(v) for v in obj]
+    if hasattr(obj, "item"):
+        try:
+            return readable(obj.item())
+        except (TypeError, ValueError):
+            pass
+    if hasattr(obj, "tolist"):
+        return readable(obj.tolist())
+    return obj