insightfactory-cli 1.0.0.dev1__py3-none-any.whl

if_cli/commands/profiles.py

@@ -0,0 +1,119 @@
+from __future__ import annotations
+
+import json
+import sys
+import time
+from typing import Literal, TypedDict
+
+from if_cli.cache import TokenCache, is_fresh, load_cache
+from if_cli.cli import Options, parse_args
+from if_cli.colour import Colour, colourise
+from if_cli.config import config_file, get_profile, load_config
+from if_cli.runtime import format_expiry
+
+TokenStatus = Literal["valid", "expired", "none", "unknown"]
+
+
+class ProfileTokenSummary(TypedDict, total=False):
+    status: TokenStatus
+    expires_at: float
+    refreshable: bool
+    error: str
+
+
+class ProfileSummary(TypedDict, total=False):
+    name: str
+    host: str | None
+    token: ProfileTokenSummary
+    error: str
+
+
+PROFILES_OPTIONS: Options = {
+    "json": {"type": "boolean", "default": False},
+}
+
+
+def summarize_profiles(
+    config: dict[str, dict[str, str]],
+    cache: TokenCache,
+    cache_error: str | None,
+    now: float,
+) -> list[ProfileSummary]:
+    summaries: list[ProfileSummary] = []
+    for section in config:
+        name = "DEFAULT" if section == "" else section
+        try:
+            profile = get_profile(config, name)
+        except Exception as error:
+            summaries.append(
+                {
+                    "name": name,
+                    "host": config[section].get("host") or None,
+                    "token": {"status": "unknown"},
+                    "error": str(error),
+                }
+            )
+            continue
+
+        entry = cache["tokens"].get(profile["host"])
+        token: ProfileTokenSummary
+        if cache_error:
+            token = {"status": "unknown", "error": cache_error}
+        elif not entry:
+            token = {"status": "none"}
+        else:
+            token = {
+                "status": "valid" if is_fresh(entry, now) else "expired",
+                "expires_at": entry["expires_at"],
+                "refreshable": "refresh_token" in entry,
+            }
+        summaries.append({"name": name, "host": profile["host"], "token": token})
+    return summaries
+
+
+def _describe_token(token: ProfileTokenSummary) -> tuple[str, Colour]:
+    status = token["status"]
+    if status == "unknown":
+        return f"token cache unavailable ({token.get('error')})", "red"
+    if status == "none":
+        return "no token", "red"
+    if status == "valid":
+        expiry = "" if token.get("expires_at") is None else f" until {format_expiry(int(token['expires_at']))}"
+        refreshable = " (refreshable)" if token.get("refreshable") else ""
+        return f"valid{expiry}{refreshable}", "green"
+    if status == "expired":
+        refreshable = " (refreshable)" if token.get("refreshable") else ""
+        return f"expired{refreshable}", "yellow" if token.get("refreshable") else "red"
+    return str(status), "red"
+
+
+def profiles_command(argv: list[str] | None = None) -> None:
+    values, _positionals = parse_args(argv or [], options=PROFILES_OPTIONS)
+    config = load_config()
+    if len(config) == 0:
+        if values["json"]:
+            sys.stdout.write("[]\n")
+            return
+        sys.stdout.write(f"no profiles configured in {config_file()}\n")
+        return
+
+    cache: TokenCache = {"version": 1, "tokens": {}}
+    cache_error: str | None = None
+    try:
+        cache = load_cache()
+    except Exception as error:
+        cache_error = str(error)
+
+    summaries = summarize_profiles(config, cache, cache_error, time.time())
+    if values["json"]:
+        sys.stdout.write(f"{json.dumps(summaries, indent=2)}\n")
+        return
+
+    for summary in summaries:
+        if summary.get("error"):
+            status = f"misconfigured ({summary['error']})"
+            colour = "red"
+        else:
+            status, colour = _describe_token(summary["token"])
+        host = summary.get("host") or "<no host>"
+        sys.stdout.write(f"{summary['name']:<20} {host:<55} {colourise(status, colour)}\n")

if_cli/commands/set_token.py

@@ -0,0 +1,62 @@
+from __future__ import annotations
+
+import getpass
+import math
+import sys
+import time
+
+from if_cli.cache import store_tokens
+from if_cli.cli import Options, parse_args
+from if_cli.config import get_profile, load_config, resolve_profile_name
+from if_cli.runtime import die, format_expiry, jwt_exp
+
+SET_TOKEN_OPTIONS: Options = {
+    "profile": {"type": "string", "short": "p"},
+}
+
+
+def _read_hidden_token() -> str:
+    """Read a token without echoing it, matching the Node CLI's hidden-input behaviour."""
+    try:
+        if sys.stdin.isatty():
+            return getpass.getpass("").strip()
+        line = sys.stdin.readline()
+        if line == "":
+            die("no token provided")
+        return line.strip()
+    except KeyboardInterrupt:
+        try:
+            sys.stderr.write("\n")
+        except BrokenPipeError:
+            pass
+        die("token input cancelled")
+    except EOFError:
+        die("no token provided")
+
+
+def set_token_command(argv: list[str]) -> None:
+    values, _positionals = parse_args(argv, options=SET_TOKEN_OPTIONS)
+    profile = get_profile(load_config(), resolve_profile_name(values["profile"]))
+    sys.stderr.write("Paste the access token (from Profile → Developer → Copy token), then Enter:\n")
+    sys.stderr.flush()
+    token = _read_hidden_token()
+    if not token:
+        die("no token provided")
+
+    expiry = jwt_exp(token)
+    now = math.floor(time.time())
+    if expiry is not None and expiry <= now:
+        die("the provided access token is already expired")
+    entry = store_tokens(
+        profile["host"],
+        {
+            "access_token": token,
+            "expires_in": 3600 if expiry is None else expiry - now,
+        },
+        "",
+        None,
+        replace=True,
+    )
+    sys.stdout.write(
+        f"✓ stored static token for {profile['host']} (expires {format_expiry(int(entry['expires_at']))})\n"
+    )

if_cli/commands/token.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+import re
+import sys
+
+from if_cli.cli import Options, parse_args
+from if_cli.config import get_profile, load_config, resolve_profile_name
+from if_cli.oauth import get_valid_token
+from if_cli.runtime import die
+
+TOKEN_OPTIONS: Options = {
+    "profile": {"type": "string", "short": "p"},
+    "env": {"type": "boolean", "default": False},
+    "env-name": {"type": "string"},
+}
+
+
+def shell_quote(value: str) -> str:
+    return "'" + value.replace("'", "'\\''") + "'"
+
+
+def token_command(argv: list[str]) -> None:
+    values, _positionals = parse_args(argv, options=TOKEN_OPTIONS)
+    profile = get_profile(load_config(), resolve_profile_name(values["profile"]))
+    environment_name = values["env-name"] or "INSIGHTFACTORY_ACCESS_TOKEN"
+    if not re.match(r"^[A-Za-z_][A-Za-z0-9_]*$", environment_name):
+        die(f"environment variable name '{environment_name}' is invalid")
+    token = get_valid_token(profile)
+    if values["env"] or values["env-name"]:
+        sys.stdout.write(f"export {environment_name}={shell_quote(token)}\n")
+    else:
+        sys.stdout.write(f"{token}\n")

if_cli/config.py

@@ -0,0 +1,188 @@
+from __future__ import annotations
+
+import json
+import os
+import re
+import uuid
+from typing import TypedDict
+
+from if_cli.constants import DEFAULT_CALLBACK_PORT, ENV_PROFILE
+from if_cli.http import normalize_origin, validate_audience_url
+from if_cli.runtime import die
+
+INI_UNSAFE_VALUE = re.compile(r"[\r\n]")
+INI_UNSAFE_SECTION = re.compile(r"[\[\]\r\n]")
+
+
+class Profile(TypedDict):
+    name: str
+    host: str
+    audience: str
+    callback_port: int
+    client_id: str | None
+    organization: str | None
+
+
+def config_dir() -> str:
+    if "INSIGHTFACTORY_CONFIG_DIR" in os.environ:
+        return os.environ["INSIGHTFACTORY_CONFIG_DIR"]
+    return os.path.join(os.path.expanduser("~"), ".insightfactory")
+
+
+def config_file() -> str:
+    return os.path.join(config_dir(), "config")
+
+
+def cache_file() -> str:
+    return os.path.join(config_dir(), "token-cache.json")
+
+
+def empty_section() -> dict[str, str]:
+    return {}
+
+
+def load_config() -> dict[str, dict[str, str]]:
+    config: dict[str, dict[str, str]] = {}
+    try:
+        with open(config_file(), encoding="utf-8") as handle:
+            raw = handle.read()
+    except OSError:
+        return config
+
+    section = ""
+    for line in raw.split("\n"):
+        trimmed = line.strip()
+        if not trimmed or trimmed.startswith("#") or trimmed.startswith(";"):
+            continue
+
+        header = re.match(r"^\[(.+)\]$", trimmed)
+        if header:
+            section_name = header.group(1)
+            section = "" if section_name == "DEFAULT" else section_name
+            config.setdefault(section, empty_section())
+            continue
+
+        equals_index = trimmed.find("=")
+        if equals_index > 0:
+            config.setdefault(section, empty_section())[trimmed[:equals_index].strip()] = trimmed[
+                equals_index + 1 :
+            ].strip()
+
+    return config
+
+
+def save_config(config: dict[str, dict[str, str]]) -> None:
+    lines = ["# Managed by if-cli; comments are not preserved when this file is updated.", ""]
+    for section, values in config.items():
+        profile_name = "DEFAULT" if section == "" else section
+        if len(values) == 0:
+            continue
+        if INI_UNSAFE_SECTION.search(section):
+            die(
+                f"cannot save profile {json.dumps(profile_name)}: its section name contains [, ], a newline, "
+                f"or a carriage return; fix this section in the config file at {config_file()}"
+            )
+        lines.append(f"[{profile_name}]")
+        for key, value in values.items():
+            if INI_UNSAFE_VALUE.search(key) or INI_UNSAFE_VALUE.search(value):
+                die(
+                    f"cannot save profile {json.dumps(profile_name)} key {json.dumps(key)}: keys and values "
+                    f"cannot contain newlines or carriage returns; fix this entry in the config file at {config_file()}"
+                )
+            lines.append(f"{key} = {value}")
+        lines.append("")
+    write_private_file(config_file(), "\n".join(lines))
+
+
+def write_private_file(file: str, contents: str) -> None:
+    directory = os.path.dirname(file)
+    os.makedirs(directory, mode=0o700, exist_ok=True)
+    os.chmod(directory, 0o700)
+    temporary_file = f"{file}.{os.getpid()}.{uuid.uuid4()}.tmp"
+    descriptor: int | None = None
+    try:
+        descriptor = os.open(temporary_file, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
+        try:
+            os.write(descriptor, contents.encode("utf-8"))
+            os.fchmod(descriptor, 0o600)
+            os.fsync(descriptor)
+        finally:
+            os.close(descriptor)
+            descriptor = None
+        os.replace(temporary_file, file)
+        os.chmod(file, 0o600)
+        directory_descriptor: int | None = None
+        try:
+            directory_descriptor = os.open(directory, os.O_RDONLY)
+            os.fsync(directory_descriptor)
+        except OSError:
+            pass
+        finally:
+            if directory_descriptor is not None:
+                os.close(directory_descriptor)
+    finally:
+        if descriptor is not None:
+            try:
+                os.close(descriptor)
+            except OSError:
+                pass
+        try:
+            os.unlink(temporary_file)
+        except OSError:
+            pass
+
+
+def meaningful(value: str | None) -> str | None:
+    return value if value and value.strip() else None
+
+
+def parse_callback_port(value: str | None) -> int:
+    if value is None:
+        return DEFAULT_CALLBACK_PORT
+    try:
+        port = float(value)
+    except (TypeError, ValueError):
+        die(f"callback port must be an integer between 1 and 65535 (received '{value}')")
+    if port != int(port) or int(port) < 1 or int(port) > 65_535:
+        die(f"callback port must be an integer between 1 and 65535 (received '{value}')")
+    return int(port)
+
+
+def resolve_profile_name(flag: str | None = None) -> str:
+    if flag is not None:
+        name = flag
+    elif ENV_PROFILE in os.environ:
+        name = os.environ[ENV_PROFILE]
+    else:
+        name = "DEFAULT"
+    if name == "" or name != name.strip() or re.search(r"[\[\]=\r\n]", name):
+        die(
+            f"invalid profile name {json.dumps(name)}: names must be non-empty, have no leading or trailing "
+            "whitespace, and must not contain [, ], =, newlines, or carriage returns"
+        )
+    return name
+
+
+def get_profile(config: dict[str, dict[str, str]], name: str) -> Profile:
+    section_key = "" if name == "DEFAULT" else name
+    if section_key not in config:
+        die(f"profile '{name}' not found in {config_file()} — run: if-cli login -p {name} --host <factory-url>")
+    section = config[section_key]
+
+    host = section.get("host")
+    if not host:
+        die(f"profile '{name}' has no host configured")
+    normalized_host = normalize_origin(host, f"host for profile '{name}'")
+    audience_value = section.get("audience")
+    return {
+        "name": name,
+        "host": normalized_host,
+        "client_id": meaningful(section.get("client_id")),
+        "organization": meaningful(section.get("organization")),
+        "audience": (
+            validate_audience_url(audience_value, f"audience for profile '{name}'")
+            if audience_value
+            else f"{normalized_host}/api"
+        ),
+        "callback_port": parse_callback_port(section.get("callback_port")),
+    }

if_cli/constants.py

@@ -0,0 +1,5 @@
+ENV_PROFILE: str = "INSIGHTFACTORY_CONFIG_PROFILE"
+DEFAULT_SCOPE: str = "openid profile email offline_access"
+LOOPBACK_HOST: str = "127.0.0.1"
+DEFAULT_CALLBACK_PORT: int = 53682
+EXPIRY_SLACK_SECONDS: int = 60

if_cli/http.py

@@ -0,0 +1,153 @@
+from __future__ import annotations
+
+import json
+import socket
+import urllib.error
+import urllib.request
+from email.message import Message
+from urllib.parse import ParseResult, urljoin, urlparse
+
+from if_cli.runtime import die
+
+REQUEST_TIMEOUT_MS = 30_000
+
+
+def _with_backslashes_as_slashes(value: str) -> str:
+    return value.replace("\\", "/")
+
+
+def parse_url(value: str, base: str | None = None) -> ParseResult:
+    normalized = _with_backslashes_as_slashes(value)
+    if base is not None:
+        return urlparse(urljoin(_with_backslashes_as_slashes(base), normalized))
+    return urlparse(normalized)
+
+
+def _host_for_url(hostname: str) -> str:
+    return f"[{hostname}]" if ":" in hostname else hostname
+
+
+def url_origin(parsed: ParseResult) -> str:
+    if parsed.scheme not in {"http", "https"} or not parsed.hostname:
+        return "null"
+    host = _host_for_url(parsed.hostname)
+    port = parsed.port
+    default_port = 443 if parsed.scheme == "https" else 80
+    if port is not None and port != default_port:
+        return f"{parsed.scheme}://{host}:{port}"
+    return f"{parsed.scheme}://{host}"
+
+
+def url_href(parsed: ParseResult) -> str:
+    scheme = parsed.scheme.lower()
+    hostname = parsed.hostname
+    if not hostname:
+        raise ValueError("URL has no hostname")
+    host = _host_for_url(hostname)
+    userinfo = ""
+    if parsed.username:
+        userinfo = parsed.username
+        if parsed.password is not None:
+            userinfo += f":{parsed.password}"
+        userinfo += "@"
+    port = parsed.port
+    default_port = 443 if scheme == "https" else 80 if scheme == "http" else None
+    port_part = f":{port}" if port is not None and port != default_port else ""
+    path = parsed.path if parsed.path else "/"
+    query = f"?{parsed.query}" if parsed.query else ""
+    fragment = f"#{parsed.fragment}" if parsed.fragment else ""
+    return f"{scheme}://{userinfo}{host}{port_part}{path}{query}{fragment}"
+
+
+def _is_loopback(hostname: str | None) -> bool:
+    if hostname is None:
+        return False
+    return hostname in {"localhost", "127.0.0.1", "::1", "[::1]"}
+
+
+def parse_http_url(value: str, label: str) -> ParseResult:
+    try:
+        parsed = parse_url(value)
+    except ValueError:
+        die(f"{label} must be a valid URL")
+    if parsed.scheme not in {"http", "https"} or not parsed.hostname:
+        die(f"{label} must be a valid URL")
+    loopback = _is_loopback(parsed.hostname)
+    if parsed.scheme != "https" and not (parsed.scheme == "http" and loopback):
+        die(f"{label} must use HTTPS (HTTP is allowed only for localhost)")
+    return parsed
+
+
+def validate_http_url(value: str, label: str) -> str:
+    return url_href(parse_http_url(value, label))
+
+
+def validate_audience_url(value: str, label: str) -> str:
+    parse_http_url(value, label)
+    if any(ord(character) <= 0x20 or ord(character) == 0x7F for character in value):
+        die(f"{label} must not contain ASCII control characters or spaces")
+    return value
+
+
+def normalize_origin(value: str, label: str) -> str:
+    parsed = parse_http_url(value, label)
+    path = parsed.path if parsed.path else "/"
+    if parsed.username or parsed.password or path != "/" or parsed.query or parsed.fragment:
+        die(f"{label} must be a bare origin without credentials, a path, query, or fragment")
+    return url_origin(parsed)
+
+
+class HttpResponse:
+    def __init__(self, status: int, headers: Message | None, body: bytes) -> None:
+        self.status = status
+        self.headers = headers
+        self._body = body
+
+    @property
+    def ok(self) -> bool:
+        return 200 <= self.status < 300
+
+    def text(self) -> str:
+        return self._body.decode("utf-8", errors="replace")
+
+    def json(self) -> object:
+        return json.loads(self.text())
+
+    def header(self, name: str) -> str | None:
+        if self.headers is None:
+            return None
+        value = self.headers.get(name)
+        if value is None:
+            return None
+        return str(value)
+
+
+def fetch_with_timeout(
+    url: str,
+    *,
+    method: str = "GET",
+    headers: dict[str, str] | None = None,
+    body: str | bytes | None = None,
+) -> HttpResponse:
+    data: bytes | None
+    if body is None:
+        data = None
+    elif isinstance(body, bytes):
+        data = body
+    else:
+        data = body.encode("utf-8")
+    request = urllib.request.Request(url, data=data, headers=headers or {}, method=method)
+    try:
+        with urllib.request.urlopen(request, timeout=REQUEST_TIMEOUT_MS / 1000) as response:
+            return HttpResponse(response.status, response.headers, response.read())
+    except urllib.error.HTTPError as error:
+        return HttpResponse(error.code, error.headers, error.read())
+    except urllib.error.URLError as error:
+        reason = error.reason
+        if isinstance(reason, (TimeoutError, socket.timeout)) or getattr(reason, "errno", None) == getattr(
+            socket, "ETIMEDOUT", None
+        ):
+            die(f"request timed out after {REQUEST_TIMEOUT_MS / 1000}s: {url}")
+        raise
+    except TimeoutError:
+        die(f"request timed out after {REQUEST_TIMEOUT_MS / 1000}s: {url}")

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)