datalegion-cli 1.2.2__tar.gz → 1.3.1__tar.gz

{datalegion_cli-1.2.2 → datalegion_cli-1.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: datalegion-cli
-Version: 1.2.2
+Version: 1.3.1
 Summary: CLI for the Data Legion API — agent-friendly, fully async
 Project-URL: Homepage, https://www.datalegion.ai
 Project-URL: Documentation, https://www.datalegion.ai/docs
@@ -96,7 +96,17 @@ uv sync
 
 ## Configuration
 
-Set your API key (stored encrypted on disk):
+Sign in with your Data Legion account (admin or developer role) and the CLI stores a key for this machine:
+
+```bash
+datalegion-cli login                 # opens a sign-in link; confirm the code it shows
+datalegion-cli login --team-id 7     # when your account has several teams
+datalegion-cli login --no-browser    # headless: prints the link to open on another device
+```
+
+The key belongs to this machine, named with a random id (`cli-` plus 8 hex characters) that the CLI generates on first login and keeps in its config, so nothing about the machine (such as its hostname) is sent. Pass `--device <name>` for a readable label instead. Signing in again replaces it, and you can disconnect it from Connected Apps in the dashboard.
+
+Or set an API key yourself (stored encrypted on disk):
 
 ```bash
 datalegion-cli config set api_key legion_your_key_here

{datalegion_cli-1.2.2 → datalegion_cli-1.3.1}/README.md

@@ -62,7 +62,17 @@ uv sync
 
 ## Configuration
 
-Set your API key (stored encrypted on disk):
+Sign in with your Data Legion account (admin or developer role) and the CLI stores a key for this machine:
+
+```bash
+datalegion-cli login                 # opens a sign-in link; confirm the code it shows
+datalegion-cli login --team-id 7     # when your account has several teams
+datalegion-cli login --no-browser    # headless: prints the link to open on another device
+```
+
+The key belongs to this machine, named with a random id (`cli-` plus 8 hex characters) that the CLI generates on first login and keeps in its config, so nothing about the machine (such as its hostname) is sent. Pass `--device <name>` for a readable label instead. Signing in again replaces it, and you can disconnect it from Connected Apps in the dashboard.
+
+Or set an API key yourself (stored encrypted on disk):
 
 ```bash
 datalegion-cli config set api_key legion_your_key_here

{datalegion_cli-1.2.2 → datalegion_cli-1.3.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "datalegion-cli"
-version = "1.2.2"
+version = "1.3.1"
 description = "CLI for the Data Legion API — agent-friendly, fully async"
 readme = "README.md"
 requires-python = ">=3.11"

{datalegion_cli-1.2.2 → datalegion_cli-1.3.1}/src/datalegion_cli/config.py

@@ -27,6 +27,7 @@ _DEFAULTS: dict[str, object] = {
     "api_key": "",
     "default_output": "json",  # json | table | raw
     "install_method": "",  # brew | github | git | pip
+    "device_id": "",  # random name for this machine's login key (see login.new_device_id)
 }
 
 # Fields that are stored encrypted on disk

datalegion_cli-1.3.1/src/datalegion_cli/login.py

@@ -0,0 +1,151 @@
+"""Sign in from the terminal and get a key for this machine (OAuth device authorization).
+
+``datalegion-cli login`` asks Data Legion's sign-in server (WorkOS AuthKit) for a
+device code, shows the person a link and a short code to approve, polls until they
+do, then trades the access token at ``POST /agent/key`` for an API key that belongs
+to this machine. The key is stored encrypted like one set with ``config set``.
+Signing in again on the same machine replaces its key; the person can disconnect it
+from the Connected Apps page in the dashboard.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import re
+import secrets
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from collections.abc import Awaitable, Callable
+
+    import httpx
+
+# The sign-in server and the CLI's OAuth app ("Data Legion CLI", a public PKCE app;
+# the id is not a secret). Overridable for testing against another environment.
+SIGNIN_URL = os.environ.get("LEGION_SIGNIN_URL", "https://signin.datalegion.ai")
+CLI_CLIENT_ID = os.environ.get("LEGION_CLI_CLIENT_ID", "client_01M4ABTVGMNFRS52XMF8YDC1H5")
+
+_DEVICE_GRANT = "urn:ietf:params:oauth:grant-type:device_code"
+# What the API accepts as a device name: words separated by single spaces.
+_DEVICE_OK = re.compile(r"^[\w.@:-]+( [\w.@:-]+)*$")
+
+
+class LoginError(Exception):
+    """Sign-in failed; the message is fit to show the person."""
+
+    def __init__(self, message: str, *, code: str = "login_failed", details: Any = None):
+        super().__init__(message)
+        self.code = code
+        self.details = details
+
+
+def new_device_id() -> str:
+    """A random name for this machine's key: ``cli-`` plus 8 hex characters.
+
+    Random rather than the hostname (or a hash of it): hostnames often carry a
+    person's name and are guessable, so nothing about the machine leaves it. Saved
+    in the config on first login and reused, so signing in again replaces this
+    machine's key instead of adding another.
+    """
+    return f"cli-{secrets.token_hex(4)}"
+
+
+def check_device_name(name: str) -> str:
+    """Return the name if the API will accept it, else raise LoginError."""
+    if not (1 <= len(name) <= 100) or not _DEVICE_OK.match(name):
+        raise LoginError(
+            "Device names use letters, digits and . _ @ : - (single spaces between words), "
+            "up to 100 characters.",
+            code="invalid_device",
+        )
+    return name
+
+
+async def start_device_authorization(client: httpx.AsyncClient) -> dict[str, Any]:
+    """Ask the sign-in server for a device code and the link the person approves at."""
+    resp = await client.post(
+        f"{SIGNIN_URL}/oauth2/device_authorization",
+        data={"client_id": CLI_CLIENT_ID, "scope": "openid"},
+    )
+    if resp.status_code != 200:
+        raise LoginError(f"Sign-in could not start ({resp.status_code}): {_oauth_error(resp)}")
+    return resp.json()
+
+
+async def poll_for_token(
+    client: httpx.AsyncClient,
+    device: dict[str, Any],
+    *,
+    sleep: Callable[[float], Awaitable[None]] = asyncio.sleep,
+) -> str:
+    """Poll until the person approves (RFC 8628), returning the access token."""
+    interval = float(device.get("interval") or 5)
+    deadline = asyncio.get_running_loop().time() + float(device.get("expires_in") or 300)
+    while asyncio.get_running_loop().time() < deadline:
+        await sleep(interval)
+        resp = await client.post(
+            f"{SIGNIN_URL}/oauth2/token",
+            data={
+                "grant_type": _DEVICE_GRANT,
+                "device_code": device["device_code"],
+                "client_id": CLI_CLIENT_ID,
+            },
+        )
+        if resp.status_code == 200:
+            token = resp.json().get("access_token")
+            if token:
+                return str(token)
+            raise LoginError("Sign-in returned no access token.")
+        error = _oauth_error(resp)
+        if error == "authorization_pending":
+            continue
+        if error == "slow_down":
+            interval += 5
+            continue
+        if error == "access_denied":
+            raise LoginError("Sign-in was declined.", code="access_denied")
+        if error == "expired_token":
+            break
+        raise LoginError(f"Sign-in failed: {error}")
+    raise LoginError("The sign-in code expired. Run `datalegion-cli login` again.", code="expired")
+
+
+async def exchange_for_key(
+    client: httpx.AsyncClient,
+    api_base_url: str,
+    access_token: str,
+    device_name: str,
+    team_id: int | None,
+) -> dict[str, Any]:
+    """Trade the access token for this machine's API key (POST /agent/key)."""
+    body: dict[str, Any] = {"device": device_name}
+    if team_id is not None:
+        body["team_id"] = team_id
+    resp = await client.post(
+        f"{api_base_url.rstrip('/')}/agent/key",
+        json=body,
+        headers={"Authorization": f"Bearer {access_token}"},
+    )
+    try:
+        payload = resp.json()
+    except ValueError:
+        payload = {}
+    if resp.status_code == 200 and payload.get("api_key"):
+        return payload
+    message = payload.get("message") or f"Getting a key failed ({resp.status_code})."
+    details = payload.get("details")
+    if resp.status_code == 409:
+        message = "This account has several teams. Run again with --team-id <id> to choose one."
+        raise LoginError(message, code="choose_team", details=details)
+    raise LoginError(
+        message, code=str(payload.get("error") or "key_exchange_failed"), details=details
+    )
+
+
+def _oauth_error(resp: httpx.Response) -> str:
+    try:
+        body = resp.json()
+    except ValueError:
+        return resp.text[:200] or str(resp.status_code)
+    return str(body.get("error") or body.get("message") or resp.status_code)

{datalegion_cli-1.2.2 → datalegion_cli-1.3.1}/src/datalegion_cli/main.py

@@ -10,9 +10,9 @@ from loguru import logger
 from datalegion_cli import __version__
 from datalegion_cli.async_typer import async_command
 from datalegion_cli.commands import company, credits, person, utility
-from datalegion_cli.config import load_config, save_config
+from datalegion_cli.config import get_base_url, load_config, save_config
 from datalegion_cli.logging import setup_logging
-from datalegion_cli.output import emit_json
+from datalegion_cli.output import console, emit_error, emit_json
 from datalegion_cli.update import check_for_update, self_update
 
 app = typer.Typer(
@@ -79,8 +79,7 @@ async def config(
         # Mask the API key for display
         display = dict(cfg)
         if display.get("api_key"):
-            k = str(display["api_key"])
-            display["api_key"] = k[:10] + "..." + k[-4:] if len(k) > 14 else "***"
+            display["api_key"] = _mask(str(display["api_key"]))
         emit_json(display)
         return
 
@@ -104,13 +103,86 @@ async def config(
         else:
             cfg[key] = value
         save_config(cfg)
-        logger.info("Set {} = {}", key, cfg[key])
-        emit_json({"ok": True, "key": key, "value": cfg[key]})
+        shown = _mask(str(cfg[key])) if key in _SECRET_KEYS else cfg[key]
+        logger.info("Set {} = {}", key, shown)
+        emit_json({"ok": True, "key": key, "value": shown})
         return
 
     raise typer.BadParameter(f"Unknown action: {action}. Use get, set, list, or path.")
 
 
+_SECRET_KEYS = {"api_key"}
+
+
+def _mask(value: str) -> str:
+    """Show enough of a secret to recognize it, never the whole value."""
+    return value[:10] + "..." + value[-4:] if len(value) > 14 else "***"
+
+
+@app.command()
+@async_command
+async def login(
+    team_id: Annotated[
+        int | None, typer.Option("--team-id", help="Team the key bills, when you have several.")
+    ] = None,
+    device: Annotated[
+        str | None,
+        typer.Option(
+            "--device", help="Name for this machine (default: a random id saved locally)."
+        ),
+    ] = None,
+    no_browser: Annotated[
+        bool, typer.Option("--no-browser", help="Print the sign-in link without opening it.")
+    ] = False,
+) -> None:
+    """Sign in with your Data Legion account and store a key for this machine.
+
+    Opens a sign-in link (approve the code it shows), then saves an API key that
+    belongs to this machine. Signing in again replaces it. Disconnect it any time
+    from Connected Apps in the dashboard.
+    """
+    import webbrowser
+
+    import httpx
+
+    from datalegion_cli import login as flow
+
+    try:
+        cfg = load_config()
+        if not device and not cfg.get("device_id"):
+            cfg["device_id"] = flow.new_device_id()
+            save_config(cfg)
+        device_name = flow.check_device_name(device or str(cfg["device_id"]))
+        async with httpx.AsyncClient(timeout=30.0) as client:
+            started = await flow.start_device_authorization(client)
+            link = started.get("verification_uri_complete") or started["verification_uri"]
+            console.print(
+                f"Open [bold]{link}[/bold] and confirm the code [bold]{started['user_code']}[/bold]."
+            )
+            if not no_browser:
+                webbrowser.open(link)
+            token = await flow.poll_for_token(client, started)
+            issued = await flow.exchange_for_key(
+                client, get_base_url(), token, device_name, team_id
+            )
+    except flow.LoginError as exc:
+        emit_error(str(exc), code=exc.code, details=exc.details, as_json=True)
+        raise typer.Exit(1) from exc
+
+    cfg = load_config()
+    cfg["api_key"] = issued["api_key"]
+    save_config(cfg)
+    emit_json(
+        {
+            "ok": True,
+            "device": device_name,
+            "team_id": issued["team_id"],
+            "api_key": _mask(issued["api_key"]),
+            "replaced": issued.get("replaced", 0),
+        }
+    )
+
+
 @app.command()
 @async_command
 async def update(

datalegion_cli-1.3.1/tests/test_login.py

@@ -0,0 +1,238 @@
+"""`datalegion-cli login`: device authorization, polling, the key exchange, and what is stored."""
+
+from __future__ import annotations
+
+import json
+import re
+from unittest.mock import AsyncMock, patch
+
+import httpx
+import pytest
+from typer.testing import CliRunner
+
+from datalegion_cli import login as flow
+from datalegion_cli.main import app
+
+runner = CliRunner()
+KEY = "legion_" + "c0ffee" * 10 + "abcd"
+
+
+def _client(handler) -> httpx.AsyncClient:
+    return httpx.AsyncClient(transport=httpx.MockTransport(handler))
+
+
+async def _no_sleep(_seconds: float) -> None:
+    return None
+
+
+@pytest.fixture
+def tmp_config(tmp_config_dir, monkeypatch):
+    """A throwaway config dir with no LEGION_API_KEY override."""
+    monkeypatch.delenv("LEGION_API_KEY", raising=False)
+    return tmp_config_dir
+
+
+class TestDeviceName:
+    def test_new_ids_are_random_and_api_safe(self):
+        ids = {flow.new_device_id() for _ in range(50)}
+        assert len(ids) == 50
+        for device_id in ids:
+            assert re.fullmatch(r"cli-[0-9a-f]{8}", device_id)
+            assert flow.check_device_name(device_id) == device_id
+
+    def test_the_hostname_is_never_read(self):
+        assert not hasattr(flow, "platform")
+
+    @pytest.mark.parametrize("name", ["", " lead", "a\nb", "x" * 101, "semi;colon", "two  spaces"])
+    def test_rejects_what_the_api_rejects(self, name):
+        with pytest.raises(flow.LoginError):
+            flow.check_device_name(name)
+
+    @pytest.mark.parametrize("name", ["laptop", "build-box.internal", "ci runner 3", "me@host:1"])
+    def test_accepts_ordinary_names(self, name):
+        assert flow.check_device_name(name) == name
+
+
+class TestFlow:
+    async def test_start_sends_the_cli_client(self):
+        seen = {}
+
+        def handler(req: httpx.Request) -> httpx.Response:
+            seen["url"] = str(req.url)
+            seen["body"] = req.content.decode()
+            return httpx.Response(200, json={"device_code": "d", "user_code": "BCDF-GHJK"})
+
+        async with _client(handler) as c:
+            out = await flow.start_device_authorization(c)
+        assert out["user_code"] == "BCDF-GHJK"
+        assert seen["url"] == "https://signin.datalegion.ai/oauth2/device_authorization"
+        assert f"client_id={flow.CLI_CLIENT_ID}" in seen["body"]
+
+    async def test_start_failure_is_reported(self):
+        async with _client(
+            lambda r: httpx.Response(400, json={"error": "unauthorized_client"})
+        ) as c:
+            with pytest.raises(flow.LoginError, match="unauthorized_client"):
+                await flow.start_device_authorization(c)
+
+    async def test_poll_waits_through_pending_and_slow_down(self):
+        answers = iter(
+            [
+                httpx.Response(400, json={"error": "authorization_pending"}),
+                httpx.Response(400, json={"error": "slow_down"}),
+                httpx.Response(200, json={"access_token": "tok"}),
+            ]
+        )
+        slept: list[float] = []
+
+        async def sleep(s: float) -> None:
+            slept.append(s)
+
+        async with _client(lambda r: next(answers)) as c:
+            token = await flow.poll_for_token(
+                c, {"device_code": "d", "interval": 5, "expires_in": 300}, sleep=sleep
+            )
+        assert token == "tok"
+        assert slept == [5, 5, 10]  # slow_down adds 5 seconds
+
+    @pytest.mark.parametrize(
+        ("error", "code"), [("access_denied", "access_denied"), ("expired_token", "expired")]
+    )
+    async def test_poll_terminal_answers(self, error, code):
+        async with _client(lambda r: httpx.Response(400, json={"error": error})) as c:
+            with pytest.raises(flow.LoginError) as exc:
+                await flow.poll_for_token(c, {"device_code": "d", "interval": 1}, sleep=_no_sleep)
+        assert exc.value.code == code
+
+    async def test_exchange_sends_the_bearer_and_device(self):
+        seen = {}
+
+        def handler(req: httpx.Request) -> httpx.Response:
+            seen["auth"] = req.headers["authorization"]
+            seen["url"] = str(req.url)
+            seen["body"] = json.loads(req.content)
+            return httpx.Response(200, json={"api_key": KEY, "team_id": 7, "replaced": 0})
+
+        async with _client(handler) as c:
+            out = await flow.exchange_for_key(c, "https://api.datalegion.ai/", "tok", "laptop", 7)
+        assert out["api_key"] == KEY
+        assert seen == {
+            "auth": "Bearer tok",
+            "url": "https://api.datalegion.ai/agent/key",
+            "body": {"device": "laptop", "team_id": 7},
+        }
+
+    async def test_exchange_several_teams(self):
+        teams = [{"team_id": 7, "team_name": "Sales"}]
+        reply = httpx.Response(
+            409, json={"error": "conflict", "message": "x", "details": {"teams": teams}}
+        )
+        async with _client(lambda r: reply) as c:
+            with pytest.raises(flow.LoginError) as exc:
+                await flow.exchange_for_key(c, "https://api.datalegion.ai", "tok", "laptop", None)
+        assert exc.value.code == "choose_team" and "--team-id" in str(exc.value)
+        assert exc.value.details == {"teams": teams}
+
+    async def test_exchange_refusal_relays_the_message(self):
+        reply = httpx.Response(
+            403,
+            json={
+                "error": "forbidden",
+                "message": "Your Data Legion account is waiting for approval.",
+            },
+        )
+        async with _client(lambda r: reply) as c:
+            with pytest.raises(flow.LoginError, match="waiting for approval"):
+                await flow.exchange_for_key(c, "https://api.datalegion.ai", "tok", "laptop", None)
+
+
+class TestLoginCommand:
+    @pytest.fixture
+    def steps(self):
+        with (
+            patch.object(
+                flow,
+                "start_device_authorization",
+                new=AsyncMock(
+                    return_value={
+                        "verification_uri": "https://signin.datalegion.ai/device",
+                        "user_code": "BCDF-GHJK",
+                        "device_code": "d",
+                    }
+                ),
+            ),
+            patch.object(flow, "poll_for_token", new=AsyncMock(return_value="tok")),
+            patch.object(
+                flow,
+                "exchange_for_key",
+                new=AsyncMock(return_value={"api_key": KEY, "team_id": 7, "replaced": 1}),
+            ) as exchange,
+            patch("webbrowser.open") as browser,
+        ):
+            yield exchange, browser
+
+    def test_stores_the_key_and_never_prints_it(self, steps, tmp_config):
+        exchange, browser = steps
+        result = runner.invoke(app, ["login", "--device", "laptop", "--team-id", "7"])
+        assert result.exit_code == 0, result.output
+        out = json.loads(result.stdout)
+        assert out["ok"] is True and out["team_id"] == 7 and out["device"] == "laptop"
+        assert KEY not in result.output and out["api_key"].endswith(KEY[-4:])
+        assert exchange.await_args.args[3:] == ("laptop", 7)
+        browser.assert_called_once()
+        from datalegion_cli.config import load_config
+
+        assert load_config()["api_key"] == KEY
+
+    def test_default_device_is_a_saved_random_id_reused_next_time(self, steps, tmp_config):
+        exchange, _ = steps
+        assert runner.invoke(app, ["login"]).exit_code == 0
+        first = exchange.await_args.args[3]
+        assert re.fullmatch(r"cli-[0-9a-f]{8}", first)
+        from datalegion_cli.config import load_config
+
+        assert load_config()["device_id"] == first
+        assert runner.invoke(app, ["login"]).exit_code == 0
+        assert exchange.await_args.args[3] == first  # same machine, same key slot
+
+    def test_device_flag_wins_and_leaves_the_saved_id(self, steps, tmp_config):
+        exchange, _ = steps
+        assert runner.invoke(app, ["login"]).exit_code == 0
+        from datalegion_cli.config import load_config
+
+        saved = load_config()["device_id"]
+        assert runner.invoke(app, ["login", "--device", "laptop"]).exit_code == 0
+        assert exchange.await_args.args[3] == "laptop"
+        assert load_config()["device_id"] == saved
+
+    def test_no_browser(self, steps, tmp_config):
+        _, browser = steps
+        assert runner.invoke(app, ["login", "--device", "laptop", "--no-browser"]).exit_code == 0
+        browser.assert_not_called()
+
+    def test_a_refusal_is_json_and_exit_1(self, steps, tmp_config):
+        exchange, _ = steps
+        exchange.side_effect = flow.LoginError(
+            "Pick a team.", code="choose_team", details={"teams": []}
+        )
+        result = runner.invoke(app, ["login", "--device", "laptop"])
+        assert result.exit_code == 1
+        assert json.loads(result.stdout) == {
+            "ok": False,
+            "error": "choose_team",
+            "message": "Pick a team.",
+            "details": {"teams": []},
+        }
+
+    def test_a_bad_device_name_stops_before_sign_in(self, steps, tmp_config):
+        result = runner.invoke(app, ["login", "--device", "semi;colon"])
+        assert result.exit_code == 1
+        assert json.loads(result.stdout)["error"] == "invalid_device"
+        flow.start_device_authorization.assert_not_awaited()
+
+
+def test_config_set_never_echoes_the_key(tmp_config):
+    result = runner.invoke(app, ["config", "set", "api_key", KEY])
+    assert result.exit_code == 0
+    assert KEY not in result.output
+    assert json.loads(result.stdout)["value"].endswith(KEY[-4:])