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

kx_auth_cli/exchange.py

@@ -0,0 +1,193 @@
+"""``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 the
+container'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 (first found wins): ``--subject`` → ``$KX_AUTH_TOKEN`` → stdin → 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 json
+import os
+import sys
+import time
+
+from kx_auth_core import OutboundConfig, exchange
+
+from . import cache
+
+EXIT_OK = 0
+EXIT_ERROR = 1
+EXIT_USAGE = 2
+EXIT_AUTH_REQUIRED = 3
+EXIT_DENIED = 4
+
+_NEEDS_SUBJECT = {"passthrough", "rfc_8693"}
+
+HELP_DESCRIPTION = (
+    "Exchange a subject token for a backend-scoped credential via the shared outbound seam "
+    "(the same code path the container's backends use). 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, or no subject token for a strategy that needs one
+  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 (first found wins):  --subject  ->  $KX_AUTH_TOKEN  ->  stdin  ->  login cache (--server)
+
+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 container'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 $KX_AUTH_TOKEN, stdin, 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.")
+    parser.add_argument("--json", action="store_true", help="Emit a structured JSON envelope (the agent path).")
+
+
+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)."""
+    if args.subject:
+        return args.subject, False
+    env = os.environ.get("KX_AUTH_TOKEN")
+    if env:
+        return env.strip(), False
+    try:
+        if not sys.stdin.isatty():
+            piped = sys.stdin.read().strip()
+            if piped:
+                return piped, False
+    except (OSError, ValueError):
+        pass
+    if args.server:
+        entry = cache.get(args.server)
+        if entry and entry.get("access_token"):
+            expires_at = entry.get("expires_at")
+            if expires_at and time.time() >= float(expires_at):
+                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 _emit(args: argparse.Namespace, *, status: str, reason: str | None = None, credential=None) -> None:
+    if args.json:
+        if credential is not None:
+            envelope = {
+                "status": status,
+                "access_token": credential.access_token,
+                "token_type": credential.token_type,
+                "expires_in": credential.expires_in,
+                "strategy": credential.strategy,
+                "claims": credential.claims,
+            }
+        else:
+            envelope = {"status": status, "reason": reason}
+        print(json.dumps(envelope, indent=2, default=str))
+        return
+    if credential is not None:
+        print(f"ok — strategy={credential.strategy} token_type={credential.token_type} access_token={credential.access_token}")
+    else:
+        print(f"{status}: {reason}", file=sys.stderr)
+
+
+def run(args: argparse.Namespace) -> int:
+    subject, cache_expired = _resolve_subject(args)
+    if args.strategy in _NEEDS_SUBJECT and not subject:
+        if cache_expired:
+            _emit(
+                args,
+                status="auth_required",
+                reason=f"the cached login for {args.server} has expired — "
+                f"run `kx auth login --server {args.server}` again",
+            )
+            return EXIT_AUTH_REQUIRED
+        print(
+            f"error: strategy '{args.strategy}' needs a subject token "
+            "(pass --subject, $KX_AUTH_TOKEN, stdin, or --server for the login cache)",
+            file=sys.stderr,
+        )
+        return EXIT_USAGE
+
+    config = _config_from_args(args)
+    try:
+        credential = asyncio.run(exchange(config, subject))
+    except PermissionError as exc:  # strategy refusal (e.g. passthrough audience guard)
+        _emit(args, status="denied", reason=str(exc))
+        return EXIT_DENIED
+    except Exception as exc:  # ValueError (misconfig / no token) / httpx / unexpected
+        _emit(args, status="error", reason=str(exc))
+        return EXIT_ERROR
+
+    _emit(args, status="ok", credential=credential)
+    return EXIT_OK

kx_auth_cli/introspect.py

@@ -0,0 +1,167 @@
+"""``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 the container enforces) 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 (so the CLI checks against the same keys
+the container uses); 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 json
+import os
+import sys
+
+from kx_auth_core import (
+    AUTH_REQUIRED,
+    DENIED,
+    ERROR,
+    OK,
+    AuthSettings,
+    VerifyResult,
+    verify_token,
+)
+
+EXIT_CODES = {OK: 0, ERROR: 1, AUTH_REQUIRED: 3, DENIED: 4}
+
+# 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 the container 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 (first found wins):  argument  ->  $KX_AUTH_TOKEN  ->  stdin
+
+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
+"""
+
+
+def add_arguments(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument(
+        "token",
+        nargs="?",
+        help="The bearer token to validate. Falls back to $KX_AUTH_TOKEN, then stdin.",
+    )
+    parser.add_argument(
+        "--json",
+        action="store_true",
+        help="Emit a structured JSON envelope (status/valid/claims/reason) — the agent path.",
+    )
+    # 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:
+    if args.token:
+        return args.token
+    env = os.environ.get("KX_AUTH_TOKEN")
+    if env:
+        return env.strip()
+    try:
+        if not sys.stdin.isatty():
+            piped = sys.stdin.read().strip()
+            if piped:
+                return piped
+    except (OSError, ValueError):
+        # stdin unavailable (e.g. captured under a test harness) — treat as "no token".
+        pass
+    return None
+
+
+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 _render(result: VerifyResult, *, json_output: bool) -> None:
+    if json_output:
+        envelope: dict = {"status": result.category, "valid": result.valid}
+        if result.valid:
+            envelope["client_id"] = result.client_id
+            envelope["scopes"] = result.scopes
+            envelope["claims"] = result.claims
+        else:
+            envelope["reason"] = result.reason
+        print(json.dumps(envelope, indent=2, default=str))
+        return
+    if result.valid:
+        print(f"valid — client_id={result.client_id} scopes={result.scopes or []}")
+    else:
+        print(f"{result.category}: {result.reason}", file=sys.stderr)
+
+
+def run(args: argparse.Namespace) -> int:
+    token = _resolve_token(args)
+    if not token:
+        print(
+            "error: no token provided (pass as an argument, $KX_AUTH_TOKEN, or via stdin)",
+            file=sys.stderr,
+        )
+        return 2  # usage error — consistent with argparse's own exit 2
+
+    try:
+        settings = _settings_from_args(args)
+        result = verify_token(token, settings)
+    except Exception as exc:  # config / unexpected failure → error
+        result = VerifyResult.fail(ERROR, str(exc))
+
+    _render(result, json_output=args.json)
+    return EXIT_CODES[result.category]

kx_auth_cli/login.py

@@ -0,0 +1,170 @@
+"""``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 container / resource server)** you connect to — *not* a backend. The container 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 container). 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 json
+import os
+import sys
+import time
+
+import httpx
+
+from . import cache, discovery
+from .discovery import DeviceAuthError, DiscoveryError
+
+EXIT_OK = 0
+EXIT_ERROR = 1
+EXIT_USAGE = 2
+EXIT_AUTH_REQUIRED = 3
+EXIT_DENIED = 4
+
+# DeviceAuthError.reason → exit code (anything unlisted is a plain error).
+_REASON_EXIT = {
+    "access_denied": EXIT_DENIED,
+    "expired_token": EXIT_AUTH_REQUIRED,
+    "timeout": EXIT_AUTH_REQUIRED,
+}
+
+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.")
+    parser.add_argument("--json", action="store_true", help="Emit a structured JSON envelope (the agent path).")
+
+
+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:
+        print(f"To authorize, open: {complete}", file=sys.stderr)
+    print(f"To authorize, visit {uri} and enter code: {code}", file=sys.stderr)
+
+
+def _emit_ok(args: argparse.Namespace, meta, token: dict, cache_path) -> None:
+    if args.json:
+        print(json.dumps(
+            {
+                "status": "ok",
+                "server": args.server,
+                "authorization_server": meta.authorization_server,
+                "access_token": token["access_token"],
+                "token_type": token.get("token_type", "Bearer"),
+                "expires_in": token.get("expires_in"),
+                "cached": True,
+                "cache_path": str(cache_path),
+            },
+            indent=2,
+            default=str,
+        ))
+        return
+    print(f"ok — logged in to {args.server} (cached at {cache_path})")
+
+
+def _emit_fail(args: argparse.Namespace, status: str, reason: str) -> None:
+    if args.json:
+        print(json.dumps({"status": status, "reason": reason}, indent=2, default=str))
+    else:
+        print(f"{status}: {reason}", file=sys.stderr)
+
+
+def run(args: argparse.Namespace) -> int:
+    scopes = _scopes(args)
+    client_id = args.client_id or os.environ.get("KX_AUTH_CLIENT_ID")
+    try:
+        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)),
+            )
+    except DiscoveryError as exc:
+        _emit_fail(args, "error", str(exc))
+        return EXIT_ERROR
+    except DeviceAuthError as exc:
+        status = "denied" if exc.reason == "access_denied" else (
+            "auth_required" if _REASON_EXIT.get(exc.reason) == EXIT_AUTH_REQUIRED else "error"
+        )
+        _emit_fail(args, status, str(exc))
+        return _REASON_EXIT.get(exc.reason, EXIT_ERROR)
+    except httpx.HTTPError as exc:
+        _emit_fail(args, "error", f"network error talking to the authorization server: {exc}")
+        return EXIT_ERROR
+
+    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)
+    _emit_ok(args, meta, token, cache_path)
+    return EXIT_OK