insightfactory-cli 1.0.0__py3-none-any.whl

if_cli/main.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+from importlib.metadata import version
+
+from if_cli.cli import run_with_handlers
+from if_cli.commands.api import api_command
+from if_cli.commands.config import config_command
+from if_cli.commands.login import login_command
+from if_cli.commands.logout import logout_command
+from if_cli.commands.profiles import profiles_command
+from if_cli.commands.set_token import set_token_command
+from if_cli.commands.token import token_command
+from if_cli.constants import ENV_PROFILE
+from if_cli.runtime import die
+
+USAGE = f"""usage: if-cli <command> [options]
+
+commands:
+  login       browser OAuth login (auth-code + PKCE via the factory /authorize proxy)
+              [-p profile] [--host url] [--client-id id] [--organization org]
+              [--audience aud] [--callback-port n] [--no-browser]
+  token       print a valid access token (auto-refreshes)
+              [-p profile] [--env] [--env-name VARIABLE]
+  logout      clear the cached token for a profile   [-p profile]
+  set-token   store a manually copied token for a profile (fallback)   [-p profile]
+  profiles    list profiles and token status   [--json]
+  config      print a non-secret profile value
+              get <host|audience|callback_port|client_id|organization> [-p profile]
+  api         call or discover factory API routes
+              [-p profile] [-X METHOD] [-d DATA] <path>
+              routes [-p profile] [filter]
+              describe [-p profile] METHOD <path>
+
+profile selection: -p flag, then ${ENV_PROFILE}, then [DEFAULT].
+"""
+
+
+def run_cli(argv: list[str]) -> None:
+    command = argv[0] if argv else None
+    rest = argv[1:]
+    if command == "login":
+        login_command(rest)
+        return
+    if command == "token":
+        token_command(rest)
+        return
+    if command == "logout":
+        logout_command(rest)
+        return
+    if command == "set-token":
+        set_token_command(rest)
+        return
+    if command == "profiles":
+        profiles_command(rest)
+        return
+    if command == "config":
+        config_command(rest)
+        return
+    if command == "api":
+        api_command(rest)
+        return
+    if command in {None, "-h", "--help"}:
+        import sys
+
+        sys.stdout.write(USAGE)
+        return
+    if command in {"-v", "--version"}:
+        import sys
+
+        sys.stdout.write(f"{version('insightfactory-cli')}\n")
+        return
+    die(f"unknown command '{command}'\n\n{USAGE}")
+
+
+def main(argv: list[str] | None = None) -> None:
+    run_with_handlers(run_cli, argv)

if_cli/oauth.py

@@ -0,0 +1,389 @@
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+import secrets
+import subprocess
+import sys
+import time
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from typing import Any
+from urllib.parse import parse_qsl, urlencode, urlparse, urlunparse
+
+from if_cli.cache import (
+    CacheEntry,
+    clear_refresh_token_if_matches,
+    is_fresh,
+    load_cache,
+    store_tokens,
+)
+from if_cli.config import Profile, meaningful
+from if_cli.constants import DEFAULT_SCOPE, LOOPBACK_HOST
+from if_cli.http import fetch_with_timeout, validate_http_url
+from if_cli.runtime import CliError, die, escape_html, is_record
+
+CALLBACK_TIMEOUT_SECONDS = 300
+RECOVERY_POLL_ATTEMPTS = 10
+RECOVERY_POLL_INTERVAL_MS = 40
+
+
+def base64url(data: bytes) -> str:
+    return base64.b64encode(data).decode("ascii").replace("+", "-").replace("/", "_").rstrip("=")
+
+
+def create_pkce_challenge(verifier: str) -> str:
+    return base64url(hashlib.sha256(verifier.encode("utf-8")).digest())
+
+
+def open_browser(url: str, launcher: str | None = None) -> None:
+    """Open ``url`` with the platform browser launcher.
+
+    A missing desktop launcher must not terminate a headless login: the
+    authorization URL is always printed as a fallback.
+    """
+    if launcher is not None:
+        command, args = launcher, [url]
+    elif sys.platform == "darwin":
+        command, args = "open", [url]
+    elif sys.platform == "win32":
+        command, args = "rundll32", ["url.dll,FileProtocolHandler", url]
+    else:
+        command, args = "xdg-open", [url]
+    try:
+        subprocess.Popen(
+            [command, *args],
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+            start_new_session=True,
+        )
+    except OSError:
+        pass
+
+
+def build_callback_url(port: int) -> str:
+    return f"http://{LOOPBACK_HOST}:{port}/callback"
+
+
+def _discover(host: str) -> dict[str, Any]:
+    response = fetch_with_timeout(f"{host}/.well-known/oauth-authorization-server")
+    if not response.ok:
+        die(f"OAuth discovery failed for {host} (HTTP {response.status})")
+    try:
+        body: object = response.json()
+    except json.JSONDecodeError:
+        die(f"OAuth discovery for {host} did not return valid JSON")
+    if not is_record(body):
+        die(f"OAuth discovery for {host} did not return a JSON object")
+    authorization_endpoint = body.get("authorization_endpoint")
+    token_endpoint = body.get("token_endpoint")
+    if not isinstance(authorization_endpoint, str) or not isinstance(token_endpoint, str):
+        die(f"OAuth discovery for {host} is missing authorization_endpoint or token_endpoint")
+    metadata: dict[str, Any] = dict(body)
+    metadata["authorization_endpoint"] = validate_http_url(authorization_endpoint, "OAuth authorization endpoint")
+    metadata["token_endpoint"] = validate_http_url(token_endpoint, "OAuth token endpoint")
+    return metadata
+
+
+class TokenRequestError(Exception):
+    def __init__(self, status: int, body: str, oauth_error: str | None = None) -> None:
+        super().__init__(f"token request failed (HTTP {status}): {body}")
+        self.status = status
+        self.oauth_error = oauth_error
+
+    @property
+    def invalidates_refresh_token(self) -> bool:
+        return self.oauth_error == "invalid_grant"
+
+
+def _parse_expires_in(value: object) -> float | None:
+    if isinstance(value, bool):
+        parsed = float("nan")
+    elif isinstance(value, (int, float)):
+        parsed = float(value)
+    elif isinstance(value, str) and value.strip():
+        try:
+            parsed = float(value)
+        except ValueError:
+            parsed = float("nan")
+    else:
+        parsed = float("nan")
+    if parsed == parsed and parsed >= 0:
+        return parsed
+    return None
+
+
+def _token_request(token_endpoint: str, form: dict[str, str]) -> dict[str, object]:
+    response = fetch_with_timeout(
+        token_endpoint,
+        method="POST",
+        headers={"Content-Type": "application/x-www-form-urlencoded"},
+        body=urlencode(form),
+    )
+    if not response.ok:
+        body = response.text()
+        oauth_error: str | None = None
+        try:
+            parsed: object = json.loads(body)
+            if is_record(parsed):
+                error_value = parsed.get("error")
+                if isinstance(error_value, str):
+                    oauth_error = error_value
+        except json.JSONDecodeError:
+            pass
+        raise TokenRequestError(response.status, body, oauth_error)
+    try:
+        tokens = response.json()
+    except json.JSONDecodeError:
+        die("token response did not include a valid access token")
+    if not is_record(tokens) or not isinstance(tokens.get("access_token"), str) or not tokens.get("access_token"):
+        die("token response did not include a valid access token")
+    expires_in = _parse_expires_in(tokens.get("expires_in"))
+    result: dict[str, object] = {"access_token": tokens["access_token"]}
+    if isinstance(tokens.get("refresh_token"), str):
+        result["refresh_token"] = tokens["refresh_token"]
+    if expires_in is not None:
+        result["expires_in"] = expires_in
+    return result
+
+
+class _CallbackServer:
+    def __init__(self, port: int, expected_state: str) -> None:
+        self.expected_state = expected_state
+        self.result: dict[str, str] | None = None
+        handler = self._handler()
+        try:
+            self.server = HTTPServer((LOOPBACK_HOST, port), handler)
+        except OSError as error:
+            die(
+                f"cannot listen on {LOOPBACK_HOST}:{port} ({error.strerror or error}) — "
+                "stop whatever is using the port and retry"
+            )
+
+    def _handler(self) -> type[BaseHTTPRequestHandler]:
+        callback = self
+
+        class Handler(BaseHTTPRequestHandler):
+            def log_message(self, format: str, *args: Any) -> None:
+                return
+
+            def do_GET(self) -> None:
+                parsed = urlparse(self.path)
+                if parsed.path != "/callback":
+                    self.send_response(404)
+                    self.end_headers()
+                    return
+                params = dict(parse_qsl(parsed.query, keep_blank_values=True))
+                if params.get("state") != callback.expected_state:
+                    self.send_response(400)
+                    self.send_header("Content-Type", "text/html; charset=utf-8")
+                    self.send_header("Connection", "close")
+                    self.end_headers()
+                    self.wfile.write(b"<h2>Login callback ignored because its state did not match.</h2>")
+                    return
+                code = params.get("code")
+                self.send_response(200)
+                self.send_header("Content-Type", "text/html; charset=utf-8")
+                self.send_header("Connection", "close")
+                self.end_headers()
+                if code:
+                    body = "<h2>Login complete — you can close this tab and return to the terminal.</h2>"
+                else:
+                    error = escape_html(params.get("error") or "")
+                    description = escape_html(params.get("error_description") or "")
+                    body = f"<h2>Login failed.</h2><pre>{error}: {description}</pre>"
+                self.wfile.write(body.encode("utf-8"))
+                callback.result = params
+
+        return Handler
+
+    def wait(self) -> dict[str, str]:
+        deadline = time.monotonic() + CALLBACK_TIMEOUT_SECONDS
+        try:
+            while self.result is None:
+                remaining = deadline - time.monotonic()
+                if remaining <= 0:
+                    die("timed out waiting for the browser callback (5 min)")
+                self.server.timeout = remaining
+                self.server.handle_request()
+        finally:
+            self.server.server_close()
+        result = self.result
+        if result is None:
+            die("timed out waiting for the browser callback (5 min)")
+        return result
+
+
+def wait_for_callback(port: int, expected_state: str) -> dict[str, str]:
+    return _CallbackServer(port, expected_state).wait()
+
+
+def login(profile: Profile, no_browser: bool, options: dict[str, str] | None = None) -> CacheEntry:
+    options = options or {}
+    metadata = _discover(profile["host"])
+    published_client_id = meaningful(
+        metadata.get("insightfactory_cli_client_id")
+        if isinstance(metadata.get("insightfactory_cli_client_id"), str)
+        else None
+    )
+    published_organization = meaningful(
+        metadata.get("insightfactory_organization_id")
+        if isinstance(metadata.get("insightfactory_organization_id"), str)
+        else None
+    )
+    stored_client_id = meaningful(profile.get("client_id"))
+    stored_organization = meaningful(profile.get("organization"))
+    pinned_client_id = meaningful(options.get("client_id_override"))
+    pinned_organization = meaningful(options.get("organization_override"))
+
+    superseded_client_id = (
+        pinned_client_id is None
+        and stored_client_id is not None
+        and published_client_id is not None
+        and stored_client_id != published_client_id
+    )
+
+    client_id = pinned_client_id or (
+        published_client_id if superseded_client_id else (stored_client_id or published_client_id)
+    )
+    organization = pinned_organization or (
+        (published_organization or stored_organization)
+        if superseded_client_id
+        else (stored_organization or published_organization)
+    )
+
+    if superseded_client_id:
+        organization_changed = organization != stored_organization and stored_organization is not None
+        sys.stderr.write(
+            f"warning: profile '{profile['name']}' has client_id {stored_client_id}, but {profile['host']} "
+            f"now advertises {published_client_id}.\n"
+            + (
+                f"         Its organization {organization} also replaces the profile's {stored_organization}.\n"
+                if organization_changed
+                else ""
+            )
+            + "         Using the advertised client. Remove client_id from the profile to silence this,\n"
+            + "         or pass --client-id (and --organization) on each login to keep overriding it.\n"
+        )
+    if not client_id:
+        die(
+            "no client id: this factory's discovery document does not publish insightfactory_cli_client_id — "
+            "pass --client-id (and --organization) with the factory's public client details"
+        )
+
+    verifier = base64url(secrets.token_bytes(48))
+    challenge = create_pkce_challenge(verifier)
+    state = base64url(secrets.token_bytes(24))
+    redirect_uri = build_callback_url(profile["callback_port"])
+    params = {
+        "response_type": "code",
+        "client_id": client_id,
+        "redirect_uri": redirect_uri,
+        "scope": DEFAULT_SCOPE,
+        "audience": profile["audience"],
+        "state": state,
+        "code_challenge": challenge,
+        "code_challenge_method": "S256",
+    }
+    if organization:
+        params["organization"] = organization
+
+    parsed_auth = urlparse(metadata["authorization_endpoint"])
+    query = dict(parse_qsl(parsed_auth.query, keep_blank_values=True))
+    query.update(params)
+    authorization_url = urlunparse(parsed_auth._replace(query=urlencode(query)))
+
+    callback_server = _CallbackServer(profile["callback_port"], state)
+    if no_browser:
+        sys.stderr.write(f"Open this URL in a browser logged into the factory:\n\n  {authorization_url}\n\n")
+    else:
+        sys.stderr.write(f"Opening browser for {profile['host']} …\n")
+        open_browser(authorization_url)
+        sys.stderr.write(f"If the browser did not open, visit:\n  {authorization_url}\n")
+
+    try:
+        callback_result = callback_server.wait()
+    except CliError:
+        raise
+    except Exception as error:
+        die(str(error))
+
+    if callback_result.get("state") != state:
+        die("state mismatch in callback — aborting")
+    if not callback_result.get("code"):
+        die(f"authorization failed: {callback_result.get('error')}: {callback_result.get('error_description')}")
+
+    tokens = _token_request(
+        metadata["token_endpoint"],
+        {
+            "grant_type": "authorization_code",
+            "client_id": client_id,
+            "code": callback_result["code"],
+            "code_verifier": verifier,
+            "redirect_uri": redirect_uri,
+        },
+    )
+    return store_tokens(profile["host"], tokens, metadata["token_endpoint"], client_id, replace=True)
+
+
+def _refresh(host: str, entry: CacheEntry, refresh_token: str, client_id: str) -> CacheEntry:
+    tokens = _token_request(
+        entry["token_endpoint"],
+        {
+            "grant_type": "refresh_token",
+            "client_id": client_id,
+            "refresh_token": refresh_token,
+        },
+    )
+    return store_tokens(host, tokens, entry["token_endpoint"], client_id)
+
+
+def _wait_for_fresh_token(host: str) -> str | None:
+    for attempt in range(RECOVERY_POLL_ATTEMPTS):
+        entry = load_cache()["tokens"].get(host)
+        if entry and is_fresh(entry):
+            return entry["access_token"]
+        if attempt + 1 < RECOVERY_POLL_ATTEMPTS:
+            time.sleep(RECOVERY_POLL_INTERVAL_MS / 1000)
+    return None
+
+
+def get_valid_token(profile: Profile) -> str:
+    entry = load_cache()["tokens"].get(profile["host"])
+    if not entry:
+        die(f"no cached token for {profile['host']} — run: if-cli login -p {profile['name']}")
+    if is_fresh(entry):
+        return entry["access_token"]
+    refresh_token = entry.get("refresh_token")
+    if refresh_token:
+        client_id = entry.get("client_id")
+        if not client_id:
+            clear_refresh_token_if_matches(profile["host"], refresh_token)
+            die(
+                f"could not refresh token for {profile['host']}: no client id cached — "
+                f"run: if-cli login -p {profile['name']}"
+            )
+        try:
+            return _refresh(profile["host"], entry, refresh_token, client_id)["access_token"]
+        except Exception as error:
+            failure: BaseException = error
+            if isinstance(error, TokenRequestError) and error.invalidates_refresh_token:
+                cleared = clear_refresh_token_if_matches(profile["host"], refresh_token)
+                if cleared:
+                    recovered_access_token = _wait_for_fresh_token(profile["host"])
+                    if recovered_access_token:
+                        return recovered_access_token
+                else:
+                    recovered = load_cache()["tokens"].get(profile["host"])
+                    recovered_refresh = recovered.get("refresh_token") if recovered else None
+                    recovered_client_id = recovered.get("client_id") if recovered else None
+                    if recovered and recovered_refresh and recovered_refresh != refresh_token and recovered_client_id:
+                        try:
+                            return _refresh(profile["host"], recovered, recovered_refresh, recovered_client_id)[
+                                "access_token"
+                            ]
+                        except Exception as retry_error:
+                            failure = retry_error
+            detail = f": {failure}" if isinstance(failure, Exception) else ""
+            die(f"could not refresh token for {profile['host']}{detail} — run: if-cli login -p {profile['name']}")
+    die(f"token for {profile['host']} expired and no refresh token cached — run: if-cli login -p {profile['name']}")

if_cli/runtime.py

@@ -0,0 +1,94 @@
+from __future__ import annotations
+
+import base64
+import json
+import os
+import signal
+import sys
+from datetime import datetime
+from typing import NoReturn, TypeGuard
+
+_exit_code = 0
+
+
+class CliError(Exception):
+    pass
+
+
+def die(message: str) -> NoReturn:
+    raise CliError(message)
+
+
+def set_exit_code(code: int) -> None:
+    global _exit_code
+    _exit_code = code
+
+
+def get_exit_code() -> int:
+    return _exit_code
+
+
+def is_record(value: object) -> TypeGuard[dict[str, object]]:
+    return isinstance(value, dict)
+
+
+def jwt_exp(token: str) -> int | None:
+    try:
+        payload = token.split(".")[1]
+        padding = "=" * ((4 - len(payload) % 4) % 4)
+        data: object = json.loads(base64.urlsafe_b64decode(payload + padding))
+        if not is_record(data):
+            return None
+        exp = data.get("exp")
+        return exp if isinstance(exp, int) else None
+    except (IndexError, ValueError, json.JSONDecodeError, TypeError):
+        return None
+
+
+def format_expiry(epoch_seconds: int) -> str:
+    return datetime.fromtimestamp(epoch_seconds).strftime("%c")
+
+
+def escape_html(value: str) -> str:
+    return (
+        value.replace("&", "&")
+        .replace("<", "&lt;")
+        .replace(">", "&gt;")
+        .replace('"', "&quot;")
+        .replace("'", "&#39;")
+    )
+
+
+def install_broken_pipe_handlers() -> None:
+    """Treat a closed stdout pipe as a normal end of output rather than a crash.
+
+    Downstream readers such as `if-cli profiles | head -1` close the pipe as
+    soon as they have the line they want. Ignoring SIGPIPE turns the subsequent
+    write into BrokenPipeError, which run_with_handlers converts into a quiet
+    exit that still reports any failure the command already recorded.
+    """
+    try:
+        signal.signal(signal.SIGPIPE, signal.SIG_IGN)
+    except (AttributeError, ValueError, OSError):
+        pass
+
+
+def handle_broken_pipe() -> NoReturn:
+    try:
+        sys.stdout.flush()
+    except (BrokenPipeError, OSError):
+        pass
+    try:
+        devnull = os.open(os.devnull, os.O_WRONLY)
+        os.dup2(devnull, sys.stdout.fileno())
+    except (OSError, ValueError, AttributeError):
+        pass
+    # Python 3.14 still flushes the original TextIOWrapper at shutdown. If that
+    # wrapper is already in an EPIPE error state, CPython maps the ignored
+    # exception to exit status 120 and overwrites SystemExit. Point sys.stdout
+    # at a fresh /dev/null stream so the shutdown flush succeeds.
+    try:
+        sys.stdout = open(os.devnull, "w", encoding="utf-8", errors="replace")
+    except OSError:
+        pass
+    raise SystemExit(get_exit_code() if isinstance(get_exit_code(), int) else 0)