cytario-cli 1.0.0__py3-none-any.whl

cytario_cli/__init__.py

@@ -0,0 +1,7 @@
+"""Cytario CLI — work with Cytario storage connections as the signed-in user."""
+
+from __future__ import annotations
+
+__version__ = "1.0.0"
+
+__all__ = ["__version__"]

cytario_cli/__main__.py

@@ -0,0 +1,8 @@
+"""Command entry point: `python -m cytario_cli`."""
+
+from __future__ import annotations
+
+from .cli import app
+
+if __name__ == "__main__":
+    app()

cytario_cli/api.py

@@ -0,0 +1,26 @@
+"""Client for cytario-web's /api/me/connections endpoint."""
+
+from __future__ import annotations
+
+import httpx
+
+from .awsconfig import Connection
+
+HTTP_UNAUTHORIZED = 401
+HTTP_OK = 200
+
+
+class ApiError(Exception):
+    """Raised when the my-connections endpoint fails."""
+
+
+def list_connections(host: str, id_token: str) -> list[Connection]:
+    """Fetch the signed-in user's visible connections with their resolved grants."""
+    url = f"{host.rstrip('/')}/api/me/connections"
+    response = httpx.get(url, headers={"Authorization": f"Bearer {id_token}"}, timeout=15)
+    if response.status_code == HTTP_UNAUTHORIZED:
+        raise ApiError("The token was rejected. Run `cytario auth login` and try again.")
+    if response.status_code != HTTP_OK:
+        raise ApiError(f"GET {url} failed ({response.status_code}): {response.text}")
+    payload = response.json()
+    return [Connection.from_api(row) for row in payload.get("connections", [])]

cytario_cli/awsconfig.py

@@ -0,0 +1,86 @@
+"""AWS CLI profile management.
+
+Writes one named profile per connection into ~/.aws/config, pointing the
+standard AWS tooling at the connection's storage role via
+``web_identity_token_file`` — the tooling performs AssumeRoleWithWebIdentity
+itself. Only profile blocks the CLI itself created are ever replaced.
+"""
+
+from __future__ import annotations
+
+import configparser
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+PROFILE_PREFIX = "cytario-"
+MANAGED_HEADER = "# managed by cytario-cli"
+AWS_CONFIG_PATH = Path.home() / ".aws" / "config"
+
+
+@dataclass
+class Connection:
+    """One row of the /api/me/connections response."""
+
+    name: str
+    bucket_name: str
+    prefix: str
+    region: str
+    s3_endpoint: str
+    sts_endpoint: str
+    role_arn: str | None
+    access_level: str | None
+
+    @classmethod
+    def from_api(cls, payload: dict) -> Connection:
+        """Build one from a /api/me/connections row."""
+        return cls(
+            name=payload["name"],
+            bucket_name=payload["bucketName"],
+            prefix=payload.get("prefix", ""),
+            region=payload["region"],
+            s3_endpoint=payload["s3Endpoint"],
+            sts_endpoint=payload["stsEndpoint"],
+            role_arn=payload.get("roleArn"),
+            access_level=payload.get("accessLevel"),
+        )
+
+    @property
+    def slug(self) -> str:
+        """Profile-safe lowercase slug of the connection name."""
+        slug = re.sub(r"[^a-z0-9-]+", "-", self.name.lower()).strip("-")
+        return slug or "connection"
+
+
+def profile_name(connection: Connection) -> str:
+    """Return the AWS CLI profile name for a connection."""
+    return f"{PROFILE_PREFIX}{connection.slug}"
+
+
+def _section_name(profile: str) -> str:
+    return f"profile {profile}"
+
+
+def write_profile(connection: Connection, token_file: Path) -> str:
+    """Upsert the AWS CLI profile block for a connection; return the profile name."""
+    config = configparser.RawConfigParser()
+    config.optionxform = str  # type: ignore[method-assign]  # keep case of AWS keys
+    if AWS_CONFIG_PATH.exists():
+        config.read(AWS_CONFIG_PATH, encoding="utf-8")
+
+    section = _section_name(profile_name(connection))
+    if not config.has_section(section):
+        config.add_section(section)
+    config.set(section, "region", connection.region)
+    config.set(section, "role_arn", connection.role_arn or "")
+    config.set(section, "web_identity_token_file", str(token_file))
+    # S3-compatible providers need explicit endpoints; AWS S3 works by default.
+    is_aws_s3 = "amazonaws.com" in connection.s3_endpoint
+    if not is_aws_s3:
+        config.set(section, "endpoint_url", connection.s3_endpoint)
+
+    AWS_CONFIG_PATH.parent.mkdir(parents=True, exist_ok=True)
+    with AWS_CONFIG_PATH.open("w", encoding="utf-8") as handle:
+        handle.write(f"{MANAGED_HEADER}\n")
+        config.write(handle)
+    return profile_name(connection)

cytario_cli/cli.py

@@ -0,0 +1,257 @@
+"""Typer CLI entry point.
+
+Commands:
+  auth login [--host <url>]        Browser sign-in (Authorization Code + PKCE,
+                                   loopback redirect). Stores the refresh grant
+                                   user-private.
+  auth token                       Print a fresh ID token (for scripts and agents).
+  auth refresh                     Refresh all managed token files.
+  auth status                      Show the signed-in host and token state.
+  connections list [--json]       List the user's connections with their grants.
+  connections setup [--all | NAME] Write AWS CLI profiles + token files.
+
+Host selection order: --host flag, CYTARIO_HOST environment variable, the
+persisted default from the last login.
+
+Usage:
+  cytario auth login --host https://app.cytario.com
+  cytario connections list --json
+  cytario connections setup --all
+  aws s3 ls --profile cytario-mybucket
+"""
+
+from __future__ import annotations
+
+import json as json_module
+import os
+import sys
+import time
+from typing import Annotated
+
+import typer
+
+from . import __version__
+from .api import ApiError, list_connections
+from .awsconfig import write_profile
+from .config import CliState, write_token_file
+from .oidc import OidcError, discover, id_token_expiry, login_flow, refresh_token
+
+app = typer.Typer(
+    help="Work with Cytario storage connections as the signed-in user.",
+    no_args_is_help=True,
+)
+auth_app = typer.Typer(help="Sign in, tokens, and sign-out state.", no_args_is_help=True)
+connections_app = typer.Typer(help="List connections and set up AWS CLI profiles.", no_args_is_help=True)
+app.add_typer(auth_app, name="auth")
+app.add_typer(connections_app, name="connections")
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        typer.echo(f"cytario {__version__}")
+        raise typer.Exit
+
+
+def _resolve_host(host: str | None) -> str:
+    if host:
+        return host.rstrip("/")
+    env_host = os.environ.get("CYTARIO_HOST")
+    if env_host:
+        return env_host.rstrip("/")
+    state = CliState.load()
+    if state:
+        return state.host
+    typer.secho(
+        "No host configured. Pass --host or run `cytario auth login --host <url>`.", fg=typer.colors.RED
+    )
+    raise typer.Exit(code=2)
+
+
+def _load_state() -> CliState:
+    state = CliState.load()
+    if not state:
+        typer.secho("Not signed in. Run `cytario auth login --host <url>`.", fg=typer.colors.RED)
+        raise typer.Exit(code=2)
+    return state
+
+
+def _fresh_id_token(state: CliState, min_validity: float = 300.0) -> str:
+    """Return an ID token with at least min_validity seconds left, refreshing as needed."""
+    if state.id_token and id_token_expiry(state.id_token) - time.time() > min_validity:
+        return state.id_token
+    typer.echo("Refreshing the ID token...")
+    tokens = refresh_token(state.token_endpoint, state.refresh_token)
+    state.refresh_token = tokens["refresh_token"]
+    state.id_token = tokens["id_token"]
+    state.id_token_expires_at = id_token_expiry(tokens["id_token"])
+    state.save()
+    return state.id_token
+
+
+@auth_app.command("login")
+def auth_login(
+    host: Annotated[str | None, typer.Option(help="Cytario host, e.g. https://app.cytario.com")] = None,
+) -> None:
+    """Sign in through the browser (Authorization Code + PKCE)."""
+    resolved_host = _resolve_host(host)
+    typer.echo(f"Signing in to {resolved_host}...")
+    try:
+        discovery = discover(resolved_host)
+        tokens = login_flow(discovery)
+    except OidcError as error:
+        typer.secho(f"Sign-in failed: {error}", fg=typer.colors.RED)
+        raise typer.Exit(code=1) from error
+    state = CliState(
+        host=resolved_host,
+        issuer=discovery.issuer,
+        authorization_endpoint=discovery.authorization_endpoint,
+        token_endpoint=discovery.token_endpoint,
+        refresh_token=tokens["refresh_token"],
+        id_token=tokens["id_token"],
+        id_token_expires_at=id_token_expiry(tokens["id_token"]),
+    )
+    state.save()
+    typer.secho(f"Signed in to {resolved_host}.", fg=typer.colors.GREEN)
+
+
+@auth_app.command("token")
+def auth_token() -> None:
+    """Print a fresh ID token to stdout."""
+    state = _load_state()
+    typer.echo(_fresh_id_token(state))
+
+
+@auth_app.command("refresh")
+def auth_refresh() -> None:
+    """Refresh every managed token file to a current ID token."""
+    state = _load_state()
+    id_token = _fresh_id_token(state)
+    _refresh_token_files(state.host, id_token)
+
+
+def _refresh_token_files(host: str, id_token: str) -> None:
+    try:
+        connections = list_connections(host, id_token)
+    except ApiError as error:
+        typer.secho(f"Could not list connections: {error}", fg=typer.colors.RED)
+        raise typer.Exit(code=1) from error
+    for connection in connections:
+        if connection.role_arn:
+            write_token_file(connection.slug, id_token)
+    typer.secho(f"Refreshed {len(connections)} token file(s).", fg=typer.colors.GREEN)
+
+
+@auth_app.command("status")
+def auth_status() -> None:
+    """Show the signed-in host and token state."""
+    state = CliState.load()
+    if not state:
+        typer.echo("Not signed in.")
+        return
+    remaining = state.id_token_expires_at - time.time() if state.id_token_expires_at else 0
+    typer.echo(f"Host: {state.host}")
+    typer.echo(f"Issuer: {state.issuer}")
+    typer.echo(f"ID token expires in: {max(remaining, 0):.0f}s" if state.id_token else "No ID token cached")
+
+
+@connections_app.command("list")
+def connections_list(
+    host: Annotated[str | None, typer.Option(help="Cytario host")] = None,
+    as_json: Annotated[bool, typer.Option("--json", help="Emit machine-readable JSON")] = False,
+) -> None:
+    """List the user's visible connections with their resolved grants."""
+    state = _load_state()
+    resolved_host = _resolve_host(host) if host else state.host
+    id_token = _fresh_id_token(state)
+    try:
+        connections = list_connections(resolved_host, id_token)
+    except ApiError as error:
+        typer.secho(str(error), fg=typer.colors.RED)
+        raise typer.Exit(code=1) from error
+
+    if as_json:
+        typer.echo(
+            json_module.dumps(
+                [
+                    {
+                        "name": connection.name,
+                        "bucketName": connection.bucket_name,
+                        "prefix": connection.prefix,
+                        "region": connection.region,
+                        "s3Endpoint": connection.s3_endpoint,
+                        "stsEndpoint": connection.sts_endpoint,
+                        "roleArn": connection.role_arn,
+                        "accessLevel": connection.access_level,
+                    }
+                    for connection in connections
+                ],
+                indent=2,
+            )
+        )
+        return
+    if not connections:
+        typer.echo("No connections visible to you.")
+        return
+    for connection in connections:
+        grant = (
+            f"{connection.access_level} ({connection.role_arn})"
+            if connection.role_arn
+            else "no applicable grant"
+        )
+        typer.echo(
+            f"{connection.name}  bucket={connection.bucket_name}  region={connection.region}  grant={grant}"
+        )
+
+
+@connections_app.command("setup")
+def connections_setup(
+    setup_all: Annotated[bool, typer.Option("--all", help="Set up every connection with a grant")] = False,
+    name: Annotated[
+        str | None, typer.Argument(help="Connection name (defaults to --all when omitted)")
+    ] = None,
+    host: Annotated[str | None, typer.Option(help="Cytario host")] = None,
+) -> None:
+    """Write an AWS CLI profile (web_identity_token_file) for each connection."""
+    state = _load_state()
+    resolved_host = _resolve_host(host) if host else state.host
+    id_token = _fresh_id_token(state)
+    try:
+        connections = list_connections(resolved_host, id_token)
+    except ApiError as error:
+        typer.secho(str(error), fg=typer.colors.RED)
+        raise typer.Exit(code=1) from error
+
+    usable = [connection for connection in connections if connection.role_arn]
+    if name:
+        usable = [connection for connection in usable if connection.name == name]
+        if not usable:
+            typer.secho(f"No connection named {name!r} with an applicable grant.", fg=typer.colors.RED)
+            raise typer.Exit(code=1)
+    elif not setup_all and usable:
+        typer.echo("No connection selected; use --all or pass a connection name.")
+        raise typer.Exit(code=2)
+
+    for connection in usable:
+        token_file = write_token_file(connection.slug, id_token)
+        profile = write_profile(connection, token_file)
+        typer.secho(
+            f"{connection.name}: profile {profile!r} ready (token {token_file}).", fg=typer.colors.GREEN
+        )
+    if not usable:
+        typer.echo("Nothing to set up — no connection has an applicable grant.")
+
+
+@app.callback()
+def main(
+    _version: Annotated[
+        bool,
+        typer.Option(
+            "--version", callback=_version_callback, help="Show the version and exit", is_eager=True
+        ),
+    ] = False,
+) -> None:
+    """Work with Cytario storage connections as the signed-in user."""
+
+
+if __name__ == "__main__":
+    sys.exit(app())

cytario_cli/config.py

@@ -0,0 +1,75 @@
+"""Local configuration and token storage.
+
+The CLI stores its host, the OIDC endpoints, and the refresh grant in a
+user-private directory (~/.config/cytario/cli). Token files consumed by the
+AWS CLI (web_identity_token_file) live under ~/.aws/cytario/<profile>/.
+Everything is written with 0600 permissions.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import stat
+from dataclasses import dataclass
+from pathlib import Path
+
+CLIENT_ID = "cytario-cli"
+SCOPE = "openid profile organization"
+SCOPE_OFFLINE = f"{SCOPE} offline_access"
+
+CONFIG_DIR = Path(os.environ.get("CYTARIO_CLI_HOME", Path.home() / ".config" / "cytario" / "cli"))
+STATE_FILE = CONFIG_DIR / "state.json"
+TOKENS_DIR = Path(os.environ.get("CYTARIO_CLI_AWS_HOME", Path.home() / ".aws" / "cytario"))
+
+FILE_MODE = stat.S_IRUSR | stat.S_IWUSR  # 0600
+
+
+@dataclass
+class CliState:
+    """Persisted between invocations: the host and the refresh grant."""
+
+    host: str
+    issuer: str
+    authorization_endpoint: str
+    token_endpoint: str
+    refresh_token: str
+    id_token: str | None = None
+    id_token_expires_at: float = 0.0  # epoch seconds; 0 = unknown
+
+    @classmethod
+    def load(cls) -> CliState | None:
+        """Read the persisted state; None when absent or truncated."""
+        try:
+            data = json.loads(STATE_FILE.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError):
+            return None
+        try:
+            return cls(
+                host=data["host"],
+                issuer=data["issuer"],
+                authorization_endpoint=data["authorization_endpoint"],
+                token_endpoint=data["token_endpoint"],
+                refresh_token=data["refresh_token"],
+                id_token=data.get("id_token"),
+                id_token_expires_at=data.get("id_token_expires_at", 0.0),
+            )
+        except KeyError:
+            return None
+
+    def save(self) -> None:
+        """Persist the state to the user-private state file (0600)."""
+        CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+        STATE_FILE.write_text(json.dumps(self.__dict__), encoding="utf-8")
+        STATE_FILE.chmod(FILE_MODE)
+
+
+def write_token_file(profile_slug: str, id_token: str) -> Path:
+    """Write the ID token for one connection profile and return its path."""
+    TOKENS_DIR.mkdir(parents=True, exist_ok=True)
+    token_dir = TOKENS_DIR / profile_slug
+    token_dir.mkdir(parents=True, exist_ok=True)
+    token_file = token_dir / "id_token"
+    token_file.write_text(id_token, encoding="utf-8")
+    token_file.chmod(FILE_MODE)
+    return token_file

cytario_cli/oidc.py

@@ -0,0 +1,214 @@
+"""OIDC Authorization Code + PKCE with a loopback redirect receiver (RFC 8252).
+
+Also covers token refresh and discovery-document lookups. The CLI never holds
+a client secret: it is a public client.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+import secrets
+import socket
+import threading
+import time
+import webbrowser
+from dataclasses import dataclass
+from urllib.parse import parse_qs, urlencode, urlparse
+
+import httpx
+
+from .config import CLIENT_ID, SCOPE_OFFLINE
+
+WELL_KNOWN_PATHS = (
+    "/.well-known/openid-configuration",
+    "/auth/realms/cytario/.well-known/openid-configuration",
+)
+
+
+@dataclass
+class Discovery:
+    """The endpoints the CLI needs from the OIDC discovery document."""
+
+    issuer: str
+    authorization_endpoint: str
+    token_endpoint: str
+
+
+class OidcError(Exception):
+    """Raised when the OIDC flow fails (network, authorization, or token)."""
+
+
+HTTP_OK = 200
+
+
+def _b64url(data: bytes) -> str:
+    return base64.urlsafe_b64encode(data).rstrip(b"=").decode("ascii")
+
+
+def _b64url_decode(segment: str) -> bytes:
+    padding = "=" * (-len(segment) % 4)
+    return base64.urlsafe_b64decode(segment + padding)
+
+
+def id_token_expiry(id_token: str) -> float:
+    """Return the `exp` claim of a JWT as epoch seconds (0 when unparsable)."""
+    try:
+        payload_segment = id_token.split(".")[1]
+        payload = json.loads(_b64url_decode(payload_segment))
+        return float(payload.get("exp", 0))
+    except (IndexError, ValueError):
+        return 0.0
+
+
+def discover(base_url: str) -> Discovery:
+    """Fetch the OIDC discovery document from a host.
+
+    `base_url` is either the cytario web host (e.g. https://app.cytario.com)
+    or the identity-service base URL itself. Both conventional locations are
+    probed.
+    """
+    base = base_url.rstrip("/")
+    last_error: Exception | None = None
+    for path in WELL_KNOWN_PATHS:
+        url = f"{base}{path}"
+        try:
+            response = httpx.get(url, timeout=10, follow_redirects=True)
+            response.raise_for_status()
+            document = response.json()
+            return Discovery(
+                issuer=document["issuer"],
+                authorization_endpoint=document["authorization_endpoint"],
+                token_endpoint=document["token_endpoint"],
+            )
+        except (httpx.HTTPError, KeyError, ValueError) as error:
+            last_error = error
+            continue
+    raise OidcError(f"Could not fetch the OIDC discovery document from {base}: {last_error}")
+
+
+class LoopbackReceiver:
+    """One-shot localhost HTTP server receiving the authorization redirect."""
+
+    def __init__(self) -> None:
+        """Bind nothing yet; the socket is created on the serve thread."""
+        self._result: dict[str, str] | None = None
+        self._ready = threading.Event()
+        self._thread = threading.Thread(target=self._serve, daemon=True)
+
+    def _serve(self) -> None:
+        server_socket = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+        server_socket.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+        server_socket.bind(("127.0.0.1", 0))
+        server_socket.listen(1)
+        self.port = server_socket.getsockname()[1]
+        self._ready.set()
+        server_socket.settimeout(300)
+        try:
+            connection, _ = server_socket.accept()
+        except (TimeoutError, OSError) as error:
+            self._result = {"error": str(error)}
+            return
+        with connection:
+            request = connection.recv(65536).decode("utf-8", errors="replace")
+            path = request.split(" ")[1] if " " in request else "/"
+            query = parse_qs(urlparse(path).query)
+            self._result = {key: values[0] for key, values in query.items()}
+            body = b"<html><body><p>Sign-in complete. You can close this window.</p></body></html>"
+            connection.sendall(
+                b"HTTP/1.1 200 OK\r\nContent-Type: text/html\r\nContent-Length: "
+                + str(len(body)).encode("ascii")
+                + b"\r\nConnection: close\r\n\r\n"
+                + body
+            )
+        server_socket.close()
+
+    def wait_ready(self) -> int:
+        """Block until the socket listens; return the bound port."""
+        self._ready.wait()
+        return self.port
+
+    def wait_for_code(self) -> dict[str, str]:
+        """Block until the browser delivered the redirect; return its params."""
+        self._thread.join()
+        if self._result is None:
+            raise OidcError("The sign-in redirect never arrived.")
+        return self._result
+
+    def start(self) -> None:
+        """Start the receiver thread."""
+        self._thread.start()
+
+
+def login_flow(discovery: Discovery) -> dict[str, str]:
+    """Run the Authorization Code + PKCE flow; return the token response.
+
+    Blocks until the user completes sign-in in the browser or the loopback
+    server times out.
+    """
+    verifier = _b64url(secrets.token_bytes(48))
+    challenge = _b64url(hashlib.sha256(verifier.encode("ascii")).digest())
+
+    receiver = LoopbackReceiver()
+    receiver.start()
+    port = receiver.wait_ready()
+    redirect_uri = f"http://127.0.0.1:{port}/"
+
+    params = {
+        "client_id": CLIENT_ID,
+        "redirect_uri": redirect_uri,
+        "response_type": "code",
+        "scope": SCOPE_OFFLINE,
+        "code_challenge": challenge,
+        "code_challenge_method": "S256",
+    }
+    authorization_url = f"{discovery.authorization_endpoint}?{urlencode(params)}"
+    webbrowser.open(authorization_url)
+
+    result = receiver.wait_for_code()
+    if "error" in result:
+        raise OidcError(f"Authorization failed: {result['error']}: {result.get('error_description', '')}")
+    if "code" not in result:
+        raise OidcError("The sign-in redirect carried no authorization code.")
+    if "state" in result:
+        pass  # state is validated by the sender via PKCE verifier uniqueness
+
+    token_response = httpx.post(
+        discovery.token_endpoint,
+        data={
+            "grant_type": "authorization_code",
+            "client_id": CLIENT_ID,
+            "code": result["code"],
+            "redirect_uri": redirect_uri,
+            "code_verifier": verifier,
+        },
+        timeout=15,
+    )
+    if token_response.status_code != HTTP_OK:
+        raise OidcError(f"The token exchange failed ({token_response.status_code}): {token_response.text}")
+    return token_response.json()
+
+
+def refresh_token(discovery_token_endpoint: str, refresh_token_value: str) -> dict[str, str]:
+    """Redeem a refresh grant; return the token response."""
+    response = httpx.post(
+        discovery_token_endpoint,
+        data={
+            "grant_type": "refresh_token",
+            "client_id": CLIENT_ID,
+            "refresh_token": refresh_token_value,
+        },
+        timeout=15,
+    )
+    if response.status_code != HTTP_OK:
+        raise OidcError(f"The token refresh failed ({response.status_code}): {response.text}")
+    return response.json()
+
+
+def token_is_fresh(id_token: str, skew_seconds: float = 300.0) -> bool:
+    """Report whether the ID token has more than the skew remaining."""
+    expiry = id_token_expiry(id_token)
+    if expiry <= 0:
+        return False
+    return time.time() < expiry - skew_seconds

cytario_cli-1.0.0.dist-info/METADATA

@@ -0,0 +1,99 @@
+Metadata-Version: 2.5
+Name: cytario-cli
+Version: 1.0.0
+Summary: CLI for working with Cytario storage connections as the signed-in user (browser OIDC sign-in, AWS CLI profile setup, token refresh)
+Project-URL: Homepage, https://github.com/cytario/cytario-cli
+Project-URL: Repository, https://github.com/cytario/cytario-cli
+Project-URL: Issues, https://github.com/cytario/cytario-cli/issues
+Project-URL: Changelog, https://github.com/cytario/cytario-cli/releases
+Author: Cytario
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agent,aws,cytario,oidc,sts,web-identity
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: typer>=0.12
+Description-Content-Type: text/markdown
+
+# cytario-cli
+
+CLI for working with [Cytario](https://github.com/cytario) storage connections
+as the signed-in user — designed for AI agents and analysts who need to work
+with connection data using the workstation's standard AWS tooling.
+
+## What it does
+
+- **`cytario auth login --host <url>`** — browser sign-in (OAuth 2.0
+  Authorization Code + PKCE against the deployment's identity service; a
+  loopback redirect receives the result). The refresh grant is stored
+  user-private (`~/.config/cytario/cli`, `0600`).
+- **`cytario connections list [--json]`** — the connections visible to you,
+  with the storage role and access level your grant resolves to.
+- **`cytario connections setup [--all | <name>]`** — writes one AWS CLI profile
+  per connection into `~/.aws/config` (`[profile cytario-<name>]`) with
+  `web_identity_token_file`, so `aws` / boto3 / pandas perform
+  `AssumeRoleWithWebIdentity` themselves — with exactly your grant's
+  authorization, never wider.
+- **`cytario auth token` / `cytario auth refresh`** — a fresh ID token on
+  stdout, and a rewrite of all managed token files (tokens live ~1 hour).
+
+Agents: see [`skills/cytario-cli.md`](skills/cytario-cli.md) for the
+tool-neutral agent workflow shipped with this repo.
+
+## Install
+
+```bash
+uv tool install cytario-cli   # or: pip install cytario-cli
+```
+
+Python ≥ 3.10. The CLI is a public OIDC client — no secrets are shipped or
+stored beyond your own refresh grant.
+
+## Usage
+
+```bash
+cytario auth login --host https://app.cytario.com
+cytario connections list
+cytario connections setup --all
+aws s3 ls --profile cytario-mybucket
+```
+
+Host resolution order: `--host`, then `CYTARIO_HOST`, then the last
+signed-in host.
+
+## Security model
+
+- Your authorization is exactly your Cytario grant on each connection
+  (`read-only` / `annotate` / `read-write` / `admin`); bucket sharing stays
+  confined to the web app.
+- No long-lived AWS keys are written; the AWS CLI federates per operation
+  from the token file, and the CLI refreshes tokens before expiry.
+- Revocation: revoking the CLI session in the identity service (or removing
+  your group membership) ends the CLI's access within one token lifetime.
+
+## Development
+
+```bash
+uv sync
+uv run ruff format --check && uv run ruff check
+uv run pytest
+```
+
+Releases are cut by [python-semantic-release](https://python-semantic-release.readthedocs.io/)
+on Conventional Commits and published to PyPI via trusted publishing.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

cytario_cli-1.0.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+cytario_cli/__init__.py,sha256=xx2d5YiBqu-h2wCdrLsNlH3qHriabaYh2nZpgKW5_zY,169
+cytario_cli/__main__.py,sha256=Ou2B8avkZnqN6QFlnppHqv9fHaamWzBnx4VyAeQJfDs,148
+cytario_cli/api.py,sha256=a9JemjlsWC4bcwbwftBJgbk0iPg-5taLAi44TIu6akY,944
+cytario_cli/awsconfig.py,sha256=tMhT8-1sD-WM8vwiyjnx9foWYW68M9dLNdiv43uNRu0,2933
+cytario_cli/cli.py,sha256=-LXrHTWNs_Pi-BMi80X1wtFV7ErNp2PuZHZoPB8g-qA,9263
+cytario_cli/config.py,sha256=ZymFCMFCovupyi9KkyyPgL-xtHOC1Q1WK-O2EMo45wc,2593
+cytario_cli/oidc.py,sha256=4PIGl6XWwP43ZCVFmFAReZyBJVbjQLXEvzNmEwiP0lY,7261
+cytario_cli-1.0.0.dist-info/METADATA,sha256=qnKlII6cluF0m70p7EALhAA0pxh0uCatAFksQkGv-Gw,3780
+cytario_cli-1.0.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+cytario_cli-1.0.0.dist-info/entry_points.txt,sha256=qRPbU8ud7vcQDxs4BaW8GUTdcZfTdrk37e2C8c2-b9M,48
+cytario_cli-1.0.0.dist-info/licenses/LICENSE,sha256=pYtRR8DCj_kycIyXmfJu2o4vbOEVkPt0ngzH4dpgw7s,1064
+cytario_cli-1.0.0.dist-info/RECORD,,

cytario_cli-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

cytario_cli-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+cytario = cytario_cli.cli:app

cytario_cli-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Cytario
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.