keystone-cli 0.1.0__py3-none-any.whl

keystone_cli/__init__.py

@@ -0,0 +1,4 @@
+"""Keystone pro-code agent CLI (``keystone``) — a thin command layer over
+``keystone-agent-sdk``. M1: ``keystone agent validate`` + ``keystone agent run`` (local dev
+loop). ``keystone login`` / ``keystone agent deploy`` = M2 (same package, extended).
+"""

keystone_cli/__main__.py

@@ -0,0 +1,24 @@
+"""``keystone`` CLI entry-point (FDP-3120). ``[project.scripts] keystone = …:app``."""
+
+from __future__ import annotations
+
+import typer
+
+from keystone_cli.commands.agent import agent_app
+from keystone_cli.commands.dev import dev
+from keystone_cli.commands.login import login
+from keystone_cli.commands.workspace import workspace_app
+
+app = typer.Typer(
+    help="Keystone pro-code agent CLI — author, validate, and run agents locally.",
+    no_args_is_help=True,
+    add_completion=False,
+)
+app.add_typer(agent_app, name="agent")
+app.add_typer(workspace_app, name="workspace")
+app.command(name="login")(login)
+app.command(name="dev")(dev)
+
+
+if __name__ == "__main__":
+    app()

keystone_cli/auth/__init__.py

@@ -0,0 +1,5 @@
+"""CLI auth — OAuth2 device flow (Keycloak) + the ~/.keystone/config.json token store (FDP-3170).
+
+`login` runs the device flow and caches the refresh token; `deploy` reads a valid access token
+(auto-refreshing) from the same store. No long-lived secret beyond the refresh token, file mode 0600.
+"""

keystone_cli/auth/device_flow.py

@@ -0,0 +1,197 @@
+"""Token acquisition for the CLI — device grant for humans, client credentials for CI (FDP-3170/3441).
+
+Pure-ish transport logic (takes an ``httpx.Client`` + injectable ``sleep``/``now``/``env`` for tests).
+The Typer command in ``commands/login`` handles printing + storing. :func:`get_access_token` is the
+read path every command uses, and it knows three ways to produce a bearer:
+
+1. ``KEYSTONE_TOKEN`` in the environment — used verbatim, never refreshed, never written to disk.
+   The CI escape hatch for when something else already minted a token.
+2. the cached access token, while it is still fresh;
+3. renewal — refresh-token grant for ``device`` mode, or a fresh client-credentials grant for
+   ``client_credentials`` mode (service accounts get no refresh token).
+"""
+
+from __future__ import annotations
+
+import os
+import time
+from collections.abc import Callable, Mapping
+from typing import Any
+
+import httpx
+
+from keystone_cli.auth.token_store import AuthConfig
+
+_DEVICE_GRANT = "urn:ietf:params:oauth:grant-type:device_code"
+_EXPIRY_SKEW = 30.0  # refresh this many seconds before the access token actually expires
+
+# Both names below are env var NAMES, never values — but three scanners see `TOKEN`/`SECRET` next to
+# a string literal and each wants its own suppression: ruff `noqa: S105`, bandit `nosec B105` (CI
+# only, not in pre-commit), detect-secrets `pragma`. Renaming to dodge them would cost the one thing
+# these constants have going for them, which is saying exactly what they are.
+#
+# Pre-minted bearer, used as-is. Named so CI can inject a token without a login step.
+ENV_TOKEN = "KEYSTONE_TOKEN"  # noqa: S105  # nosec B105
+# The client-credentials secret is read ONLY from the environment, never from a flag: a value on
+# argv is visible in `ps`, lands in shell history, and CI runners echo command lines into build logs.
+ENV_CLIENT_SECRET = "KEYSTONE_CLIENT_SECRET"  # noqa: S105  # pragma: allowlist secret  # nosec B105
+
+MODE_DEVICE = "device"
+MODE_CLIENT_CREDENTIALS = "client_credentials"
+
+
+class DeviceFlowError(Exception):
+    """Device-flow / token exchange failed (denied, expired, or transport)."""
+
+
+def _device_endpoint(issuer: str) -> str:
+    return f"{issuer.rstrip('/')}/protocol/openid-connect/auth/device"
+
+
+def _token_endpoint(issuer: str) -> str:
+    return f"{issuer.rstrip('/')}/protocol/openid-connect/token"
+
+
+def start_device_flow(client: httpx.Client, issuer: str, client_id: str) -> dict[str, Any]:
+    """Kick off the flow → device_code, user_code, verification_uri[_complete], interval, expires_in."""
+    resp = client.post(
+        _device_endpoint(issuer),
+        data={"client_id": client_id, "scope": "openid offline_access"},
+    )
+    if resp.status_code != 200:
+        raise DeviceFlowError(f"device authorization failed ({resp.status_code}): {resp.text}")
+    return resp.json()
+
+
+def poll_for_token(
+    client: httpx.Client,
+    issuer: str,
+    client_id: str,
+    device_code: str,
+    *,
+    interval: int = 5,
+    expires_in: int = 600,
+    sleep: Callable[[float], None] = time.sleep,
+    now: Callable[[], float] = time.monotonic,
+) -> dict[str, Any]:
+    """Poll the token endpoint until the user approves. Honors authorization_pending / slow_down."""
+    deadline = now() + expires_in
+    wait = interval
+    while now() < deadline:
+        resp = client.post(
+            _token_endpoint(issuer),
+            data={"grant_type": _DEVICE_GRANT, "device_code": device_code, "client_id": client_id},
+        )
+        if resp.status_code == 200:
+            return resp.json()
+        error = (
+            (resp.json() or {}).get("error")
+            if resp.headers.get("content-type", "").startswith("application/json")
+            else None
+        )
+        if error == "authorization_pending":
+            sleep(wait)
+            continue
+        if error == "slow_down":
+            wait += 5
+            sleep(wait)
+            continue
+        raise DeviceFlowError(error or f"token exchange failed ({resp.status_code})")
+    raise DeviceFlowError("device code expired before authorization")
+
+
+def refresh_access_token(client: httpx.Client, issuer: str, client_id: str, refresh_token: str) -> dict[str, Any]:
+    resp = client.post(
+        _token_endpoint(issuer),
+        data={"grant_type": "refresh_token", "refresh_token": refresh_token, "client_id": client_id},
+    )
+    if resp.status_code != 200:
+        raise DeviceFlowError(f"token refresh failed ({resp.status_code}) — run `keystone login` again")
+    return resp.json()
+
+
+def client_credentials_token(client: httpx.Client, issuer: str, client_id: str, client_secret: str) -> dict[str, Any]:
+    """Mint an access token for a Keycloak **service account** (no browser, no human).
+
+    Keycloak issues no refresh token for this grant, so there is nothing to persist for renewal —
+    the secret in the environment IS the renewal mechanism.
+    """
+    resp = client.post(
+        _token_endpoint(issuer),
+        data={"grant_type": "client_credentials", "client_id": client_id, "client_secret": client_secret},
+    )
+    if resp.status_code != 200:
+        # Surface only the OAuth error code, never the raw body: the request carried a secret and a
+        # verbose failure is the kind of thing that ends up pasted into a ticket.
+        reason = ""
+        try:
+            payload = resp.json()
+            reason = f" — {payload.get('error', '')} {payload.get('error_description', '')}".rstrip()
+        except ValueError:
+            pass
+        raise DeviceFlowError(
+            f"client-credentials grant failed ({resp.status_code}){reason}. Check {ENV_CLIENT_SECRET} and that "
+            f"the Keycloak client '{client_id}' has service accounts enabled."
+        )
+    return resp.json()
+
+
+def apply_token_response(cfg: AuthConfig, token: dict[str, Any], *, now: Callable[[], float] = time.time) -> AuthConfig:
+    """Fold a token response into the config (access + refresh + expiry). Refresh token may be rotated."""
+    cfg.access_token = token.get("access_token", "")
+    if token.get("refresh_token"):
+        cfg.refresh_token = token["refresh_token"]
+    cfg.expires_at = now() + float(token.get("expires_in", 0))
+    return cfg
+
+
+def get_access_token(
+    cfg: AuthConfig,
+    *,
+    client: httpx.Client | None = None,
+    now: Callable[[], float] = time.time,
+    save: Callable[[AuthConfig], None] | None = None,
+    env: Mapping[str, str] | None = None,
+) -> str:
+    """Return a valid bearer. Every command goes through here.
+
+    Order, and why: an explicitly injected ``KEYSTONE_TOKEN`` wins over the cache, because in CI a
+    stale ``~/.keystone/config.json`` left in the image would otherwise silently deploy as the wrong
+    identity. Then the cache while fresh, then renewal per :attr:`AuthConfig.auth_mode`.
+    """
+    env = os.environ if env is None else env
+
+    injected = (env.get(ENV_TOKEN) or "").strip()
+    if injected:
+        # Used verbatim: we hold no refresh token for it and it is not ours to renew. Deliberately
+        # NOT written to the config file — persisting an injected credential would leak it out of the
+        # job that owns it into a file that outlives it.
+        return injected
+
+    if cfg.access_token and cfg.expires_at - _EXPIRY_SKEW > now():
+        return cfg.access_token
+
+    owns_client = client is None
+    client = client or httpx.Client(timeout=30)
+    try:
+        if cfg.auth_mode == MODE_CLIENT_CREDENTIALS:
+            secret = (env.get(ENV_CLIENT_SECRET) or "").strip()
+            if not secret:
+                raise DeviceFlowError(
+                    f"this config was created with --client-credentials but {ENV_CLIENT_SECRET} is not set — "
+                    f"export it (the grant has no refresh token, so the secret is how the token is renewed)"
+                )
+            token = client_credentials_token(client, cfg.issuer, cfg.client_id, secret)
+        else:
+            if not cfg.refresh_token:
+                raise DeviceFlowError(
+                    f"not logged in — run `keystone login`, or set {ENV_TOKEN} / use --client-credentials for CI"
+                )
+            token = refresh_access_token(client, cfg.issuer, cfg.client_id, cfg.refresh_token)
+    finally:
+        if owns_client:
+            client.close()
+    apply_token_response(cfg, token, now=now)
+    if save:
+        save(cfg)
+    return cfg.access_token

keystone_cli/auth/token_store.py

@@ -0,0 +1,71 @@
+"""``~/.keystone/config.json`` — CLI auth + endpoint store, mode 0600 (FDP-3170).
+
+Holds the Keycloak issuer + client id, the platform API base (for ``deploy``), and the cached tokens.
+Only the **refresh token** is long-lived; the access token is a short-lived cache re-derived on demand.
+Path override via ``KEYSTONE_CONFIG`` (tests / CI).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import asdict, dataclass, fields
+from pathlib import Path
+
+# Baked platform defaults so `keystone login` works with NO flags (like `aws sso login`). NOT secrets —
+# client id is a public identifier, issuer/api are public URLs. Override via --flags / KEYSTONE_* env for
+# other envs (qc/staging) or local testing; after first login these are cached in the config file.
+# dev realm `aip`, Ops-provisioned device-grant client (2026-07-22). Host = keycloak-platform (public),
+# NOT keycloak-platform-admin. Override per env with --issuer / KEYSTONE_ISSUER (qc/staging).
+DEFAULT_ISSUER = "https://keycloak-platform.ops.onemount.dev/realms/aip"
+DEFAULT_CLIENT_ID = "keystone-cli"
+DEFAULT_API_BASE = "https://keystone-api-dev.aws.int.onenexus.dev"
+
+
+@dataclass
+class AuthConfig:
+    issuer: str = ""  # Keycloak realm URL, e.g. https://<kc>/realms/aip-dev
+    client_id: str = ""  # a PUBLIC Keycloak client with the device grant enabled (Ops-provisioned)
+    api_base: str = ""  # platform API base (through Kong), used by `deploy`
+    # FDP-3072 §11.4b — the agent DATA-PLANE base (invoke/hitl/runs), which moves to the pro-code
+    # cluster's own hostname (keystone-agent-api-<env>.aws.int…) once Ops lands it. Empty = fall back
+    # to api_base, so behavior is unchanged until the new domain exists. Control-plane calls
+    # (login/deploy/status → agent-hub) always stay on api_base.
+    agent_api_base: str = ""
+    refresh_token: str = ""
+    access_token: str = ""
+    expires_at: float = 0.0  # epoch seconds — access_token expiry
+    # FDP-3170 — the workspace `deploy` targets (sent as X-Workspace-ID). A user belongs to an entity
+    # (from the JWT), but picks a workspace per session — set via `keystone workspace use`. The name is
+    # cached only for display. load() ignores unknown keys, so older config files stay compatible.
+    workspace_id: str = ""
+    workspace_name: str = ""
+    # FDP-3441 — which grant minted these tokens, so the read path knows how to renew them.
+    # ``device`` (default, a human approved in a browser → renew with the refresh token) or
+    # ``client_credentials`` (a CI service account → no refresh token exists; renew by re-running
+    # the grant with the secret from the environment). Older config files lack the key and load as
+    # ``device``, which is what they are.
+    auth_mode: str = "device"
+
+
+def config_path() -> Path:
+    """Config file path. ``KEYSTONE_CONFIG`` overrides (tests); default ``~/.keystone/config.json``."""
+    override = os.environ.get("KEYSTONE_CONFIG")
+    return Path(override) if override else Path.home() / ".keystone" / "config.json"
+
+
+def load() -> AuthConfig:
+    path = config_path()
+    if not path.exists():
+        return AuthConfig()
+    data = json.loads(path.read_text())
+    known = {f.name for f in fields(AuthConfig)}
+    return AuthConfig(**{k: v for k, v in data.items() if k in known})
+
+
+def save(cfg: AuthConfig) -> None:
+    path = config_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    # Write then lock to 0600 (owner-only) — the refresh token is a credential.
+    path.write_text(json.dumps(asdict(cfg), indent=2))
+    path.chmod(0o600)

keystone_cli/commands/__init__.py

@@ -0,0 +1 @@
+"""``keystone`` command groups."""