dataspring-cli 0.4.1__tar.gz → 0.4.3__tar.gz

{dataspring_cli-0.4.1 → dataspring_cli-0.4.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: dataspring-cli
-Version: 0.4.1
+Version: 0.4.3
 Summary: DataSpring CLI - Query metrics and manage dashboards from the terminal
 Project-URL: Homepage, https://dataspring.app
 Project-URL: Documentation, https://dataspring.app/docs
@@ -79,13 +79,17 @@ dataspring query -m total_revenue --format json > data.json
 ### Authentication
 
 ```bash
-dataspring login          # Login via Google OAuth (opens browser)
-dataspring whoami         # Show current user and organization
-dataspring logout         # Clear stored credentials
+dataspring auth login     # Device flow: approve the code in a browser signed in to DataSpring
+dataspring whoami --json  # The person, the org, where the org came from (org_from), the role
+dataspring auth logout    # Revoke this machine's keys and forget them
 dataspring org list       # List your organizations
-dataspring org switch ID  # Switch to a different organization
 ```
 
+Every command names its organization: `--org <org>`, else `DATASPRING_ORG`
+then `FORSPRING_ORG`, else `.forspring.json` (`{"org": "<org>"}`) in this
+directory or a parent, else `DATASPRING_API_KEY`'s own org, else the only
+stored key; otherwise it is refused with `org_required` (exit 2).
+
 ### Querying Metrics
 
 ```bash

{dataspring_cli-0.4.1 → dataspring_cli-0.4.3}/README.md

@@ -47,13 +47,17 @@ dataspring query -m total_revenue --format json > data.json
 ### Authentication
 
 ```bash
-dataspring login          # Login via Google OAuth (opens browser)
-dataspring whoami         # Show current user and organization
-dataspring logout         # Clear stored credentials
+dataspring auth login     # Device flow: approve the code in a browser signed in to DataSpring
+dataspring whoami --json  # The person, the org, where the org came from (org_from), the role
+dataspring auth logout    # Revoke this machine's keys and forget them
 dataspring org list       # List your organizations
-dataspring org switch ID  # Switch to a different organization
 ```
 
+Every command names its organization: `--org <org>`, else `DATASPRING_ORG`
+then `FORSPRING_ORG`, else `.forspring.json` (`{"org": "<org>"}`) in this
+directory or a parent, else `DATASPRING_API_KEY`'s own org, else the only
+stored key; otherwise it is refused with `org_required` (exit 2).
+
 ### Querying Metrics
 
 ```bash

dataspring_cli-0.4.3/cli/auth.py

@@ -0,0 +1,487 @@
+"""CLI authentication: suite standard §3 (/home/dev/workspace/forspring/docs/suite-standards.md).
+
+``dataspring auth login`` runs the device flow (RFC 8628 with PKCE,
+backend/routes_device.py): the CLI shows a code and a URL, a person signed in
+to DataSpring in any browser (this machine needs none) approves it, and the
+CLI collects an ordinary ``ds_`` API key labelled ``CLI on <hostname>`` (one
+per org with ``--all-orgs``).
+
+Credentials live in ``~/.dataspring/credentials.json`` (mode 0600): a profile
+(a key) per org. Nothing machine-wide says which one a command uses (hub
+D-99: ``auth use`` went, because two agents on one machine moved each other
+between orgs); every command resolves its org afresh, in this order
+(:meth:`CLIAuthManager.resolve`):
+
+1. ``--org`` on the command;
+2. ``DATASPRING_ORG``, then ``FORSPRING_ORG``;
+3. ``.forspring.json`` (``{"org": "noon"}``) in this directory or a parent;
+4. the key's own org, when ``DATASPRING_API_KEY`` is set (a key belongs to
+   one org);
+5. the only stored profile;
+
+else it refuses with ``org_required``, the stored orgs and the three ways to
+name one, and never prompts. ``DATASPRING_API_KEY`` always wins over the
+stored keys: with it, a named org that is not the key's is ``org_mismatch``.
+``--key`` stores a key you already have, for CI. ``dataspring auth logout``
+revokes the stored keys on the server, then forgets them.
+
+Who the person is and which org a key is for are the server's answer to
+``/api/me``; nothing here opens Firestore.
+"""
+
+import base64
+import hashlib
+import json
+import os
+import secrets
+import socket
+import time
+import webbrowser
+from dataclasses import dataclass
+from pathlib import Path
+
+import httpx
+
+from cli.refusals import EN, NAME_AN_ORG, Refusal, classify, from_body
+
+ENV_KEY = "DATASPRING_API_KEY"
+
+#: Step 2 of the org order: the product's own variable, then the suite's.
+ORG_ENV_VARS = ("DATASPRING_ORG", "FORSPRING_ORG")
+
+#: Step 3: the per-project file, committed next to the code (``{"org": "noon"}``).
+PROJECT_FILE = ".forspring.json"
+
+#: ``org_from`` for steps 4 and 5.
+FROM_KEY = ENV_KEY
+FROM_ONLY_PROFILE = "only_profile"
+
+#: Step 1, ``--org``: set by the root command (``cli.main``) for this
+#: invocation; ``None`` when not given.
+_org_flag: str | None = None
+
+
+def set_org_flag(org: str | None) -> None:
+    """``--org`` for this invocation (``cli.main``'s root callback)."""
+    global _org_flag
+    _org_flag = (org or "").strip() or None
+
+
+def _host() -> str:
+    """The backend's root (https://dataspring.app; locally http://localhost:8000)."""
+    from settings import get_settings
+
+    return get_settings().mcp_server_base_url.removesuffix("/api")
+
+
+@dataclass(frozen=True)
+class UserContext:
+    """The signed-in user as ``GET /api/me`` reports them.
+
+    Mirrors the fields of ``services.auth.UserContext`` that the CLI shows,
+    without importing the service layer: the CLI wheel ships without it.
+    """
+
+    uid: str
+    email: str
+    org_id: str | None
+    org_name: str | None
+    role: str | None
+
+    @property
+    def has_org(self) -> bool:
+        """False for an account no administrator has added to an org yet.
+
+        Since D25 sign-up creates no organization, so ``/api/me`` answers 200
+        with the three org fields null. The CLI says so rather than crashing
+        on a ``KeyError`` the way it would have.
+        """
+        return self.org_id is not None
+
+
+class AuthenticationError(Exception):
+    """Raised when authentication fails or user is not logged in.
+
+    ``exit_code`` is what the CLI ends with (suite standards §6): 1, a plain
+    failure, unless a subclass says otherwise.
+    """
+
+    exit_code = 1
+
+
+class Refused(AuthenticationError):
+    """A D-99 refusal (``cli.refusals``): not signed in, no org named, a key
+    for another org, or the server's own refusal of the key."""
+
+    def __init__(self, reason: str, note: str, fix: str | None = None):
+        self.refusal = Refusal(reason, note, fix)
+        super().__init__(self.refusal.message)
+
+    @property
+    def reason(self) -> str:
+        return self.refusal.reason
+
+    @property
+    def exit_code(self) -> int:  # type: ignore[override]
+        return self.refusal.exit_code
+
+
+class ProjectFileError(AuthenticationError):
+    """A ``.forspring.json`` that names no org: invalid input (2)."""
+
+    exit_code = 2
+
+
+@dataclass(frozen=True)
+class ResolvedOrg:
+    """Which key a command sends, for which org, and where the org came from.
+
+    ``org_id`` is ``None`` only for ``DATASPRING_API_KEY`` with no org named
+    and no stored profile holding that key: the key knows its org, and the
+    server says which (``GET /api/me``). ``org_from`` is ``--org``,
+    ``DATASPRING_ORG``, ``FORSPRING_ORG``, ``.forspring.json``,
+    ``DATASPRING_API_KEY`` or ``only_profile``; ``org_file`` is the file
+    step 3 read.
+    """
+
+    key: str
+    org_id: str | None
+    org_from: str
+    org_file: str | None = None
+
+
+def _not_signed_in(detail: str = "Not logged in.") -> Refused:
+    return Refused("not_signed_in", detail, "Run 'dataspring auth login' (or set DATASPRING_API_KEY).")
+
+
+def find_project_file(start: Path | None = None) -> Path | None:
+    """The nearest ``.forspring.json`` in ``start`` (default: the working
+    directory) or a parent."""
+    here = (start or Path.cwd()).resolve()
+    for directory in (here, *here.parents):
+        candidate = directory / PROJECT_FILE
+        if candidate.is_file():
+            return candidate
+    return None
+
+
+def read_project_org(path: Path) -> str:
+    """The ``org`` a ``.forspring.json`` names; a file that names none is an error."""
+    shape = '{"org": "<org>"}'
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as e:
+        raise ProjectFileError(f"{path} is not valid JSON ({e}); it should hold {shape}.")
+    org = data.get("org") if isinstance(data, dict) else None
+    if not isinstance(org, str) or not org.strip():
+        raise ProjectFileError(f"{path} names no org; it should hold {shape}.")
+    return org.strip()
+
+
+def named_org() -> tuple[str, str, str | None] | None:
+    """Steps 1-3 of the org order: ``(org, org_from, file)``, or None."""
+    if _org_flag:
+        return _org_flag, "--org", None
+    for var in ORG_ENV_VARS:
+        value = (os.environ.get(var) or "").strip()
+        if value:
+            return value, var, None
+    path = find_project_file()
+    if path is not None:
+        return read_project_org(path), PROJECT_FILE, str(path)
+    return None
+
+
+class CLIAuthManager:
+    """API keys for the CLI: device-flow login, a profile per org, the env var."""
+
+    CONFIG_DIR = Path.home() / ".dataspring"
+    CREDENTIALS_FILE = CONFIG_DIR / "credentials.json"
+    CONFIG_FILE = CONFIG_DIR / "config.json"
+
+    def __init__(self):
+        """Initialize the auth manager."""
+        self._ensure_config_dir()
+
+    def _ensure_config_dir(self):
+        """Create config directory if it doesn't exist."""
+        self.CONFIG_DIR.mkdir(mode=0o700, parents=True, exist_ok=True)
+
+    # -- stored profiles -------------------------------------------------
+
+    def _load(self) -> dict:
+        """``{profiles: {org: {api_key, key_id, org_name, email}}}``; empty
+        for none, or for what an older CLI stored (Google credentials, or CLI
+        tokens): those sign nobody in now. A ``current`` an older CLI wrote
+        (``auth use``) is ignored: nothing machine-wide picks the org (D-99)."""
+        if not self.CREDENTIALS_FILE.exists():
+            return {}
+        try:
+            data = json.loads(self.CREDENTIALS_FILE.read_text())
+        except json.JSONDecodeError:
+            return {}
+        return data if isinstance(data.get("profiles"), dict) else {}
+
+    def _save(self, data: dict) -> None:
+        data.pop("current", None)
+        self.CREDENTIALS_FILE.write_text(json.dumps(data, indent=2))
+        self.CREDENTIALS_FILE.chmod(0o600)
+
+    def _add_profile(self, data: dict, entry: dict, email: str | None) -> None:
+        data.setdefault("profiles", {})[entry["org_id"]] = {
+            "api_key": entry["api_key"],
+            "key_id": entry.get("key_id"),
+            "org_name": entry.get("org_name") or entry["org_id"],
+            "email": email,
+        }
+
+    def profiles(self) -> dict[str, dict]:
+        return self._load().get("profiles", {})
+
+    # -- which org, which key (hub D-99) ---------------------------------
+
+    def resolve(self) -> ResolvedOrg:
+        """The org and key for this command, in the D-99 order (module doc).
+
+        Raises:
+            Refused: ``not_signed_in`` (no key at all, or none stored for the
+                org named), ``org_required`` (several stored, none named;
+                never a prompt), ``org_mismatch`` (``DATASPRING_API_KEY`` is
+                a key for another org than the one named).
+            ProjectFileError: a ``.forspring.json`` that names no org.
+        """
+        named = named_org()
+        env_key = os.environ.get(ENV_KEY)
+        profiles = self.profiles()
+
+        if env_key:
+            stored_org = next((org for org, p in profiles.items() if p.get("api_key") == env_key), None)
+            if named is None:
+                return ResolvedOrg(env_key, stored_org, FROM_KEY)
+            org, source, path = named
+            key_org = stored_org or self._key_org(env_key)
+            if key_org != org:
+                raise Refused(
+                    "org_mismatch",
+                    f"DATASPRING_API_KEY is a key for '{key_org}', but {source} names '{org}'.",
+                    f"Name '{key_org}', or set DATASPRING_API_KEY to a key for '{org}' "
+                    "(or unset it to use a stored key).",
+                )
+            return ResolvedOrg(env_key, org, source, path)
+
+        if not profiles:
+            raise _not_signed_in()
+        if named is not None:
+            org, source, path = named
+            profile = profiles.get(org)
+            if profile is None:
+                raise Refused(
+                    "not_signed_in",
+                    f"No key for '{org}' on this machine ({source} names it); "
+                    f"stored: {', '.join(sorted(profiles))}.",
+                    f"Run 'dataspring auth login' and approve {org}, or name one of the stored orgs.",
+                )
+            return ResolvedOrg(profile["api_key"], org, source, path)
+        if len(profiles) == 1:
+            org, profile = next(iter(profiles.items()))
+            return ResolvedOrg(profile["api_key"], org, FROM_ONLY_PROFILE)
+        raise Refused(
+            "org_required",
+            "Several organizations have keys on this machine and this command names none: "
+            f"{', '.join(sorted(profiles))}.",
+            f"Name one: {NAME_AN_ORG}.",
+        )
+
+    def _key_org(self, key: str) -> str | None:
+        """The org a key not stored here belongs to, as the server says.
+        Synchronous: :meth:`resolve` runs inside the async commands too."""
+        r = httpx.get(f"{_host()}/api/me", headers={"Authorization": f"Bearer {key}"}, timeout=15.0)
+        return self._me_answer(r).get("org_id")
+
+    def resolved_org(self) -> str | None:
+        """The org a command here would use, or None when none resolves."""
+        try:
+            return self.resolve().org_id
+        except AuthenticationError:
+            return None
+
+    # -- login -----------------------------------------------------------
+
+    async def login(self, *, all_orgs: bool = False, open_browser: bool = True, timeout: float = 600.0) -> "UserContext":
+        """The device flow: show a code, wait for approval in a browser, store the key(s)."""
+        verifier = secrets.token_urlsafe(48)
+        challenge = base64.urlsafe_b64encode(hashlib.sha256(verifier.encode("ascii")).digest()).rstrip(b"=").decode("ascii")
+        try:
+            r = httpx.post(f"{_host()}/api/device/code", json={
+                "code_challenge": challenge, "code_challenge_method": "S256",
+                "hostname": socket.gethostname(), "all_orgs": all_orgs,
+            }, timeout=15.0)
+        except httpx.HTTPError as e:
+            raise AuthenticationError(f"Could not reach DataSpring: {e}")
+        if r.status_code != 200:
+            raise AuthenticationError(f"Could not start the sign-in (HTTP {r.status_code})")
+        start = r.json()
+        # flush: an agent runs this with stdout redirected, where Python
+        # buffers it; unflushed, the code appeared only after the CLI exited,
+        # too late for anyone to approve it (tick 373).
+        print(f"To sign in, open {start['verification_uri']} and enter the code {start['user_code']}")
+        print(f"  (or open {start['verification_uri_complete']})", flush=True)
+        if open_browser:
+            try:
+                webbrowser.open(start["verification_uri_complete"])
+            except Exception:
+                pass  # no browser on this machine: the URL above is enough
+
+        interval = float(start.get("interval", 5))
+        deadline = time.monotonic() + min(timeout, float(start.get("expires_in", 600)))
+        while time.monotonic() < deadline:
+            time.sleep(interval)
+            r = httpx.post(f"{_host()}/api/device/token", json={"device_code": start["device_code"], "code_verifier": verifier}, timeout=15.0)
+            if r.status_code == 200:
+                body = r.json()
+                data = self._load()
+                self._add_profile(data, body, body.get("email"))
+                for other in body.get("other_orgs") or []:
+                    self._add_profile(data, other, body.get("email"))
+                self._save(data)
+                if body.get("email"):
+                    self._save_config({"email": body["email"]})
+                # The approved org's key: the one this login is about, whatever
+                # else is stored.
+                return self._context(await self._me(body["api_key"]))
+            error = (r.json() or {}).get("error") if r.headers.get("content-type", "").startswith("application/json") else None
+            if error in ("authorization_pending", "temporarily_unavailable"):
+                continue  # temporarily_unavailable: the Forspring account did not answer; the approval waits
+            if error == "slow_down":
+                interval += 5
+                continue
+            if error == "access_denied":
+                raise AuthenticationError("The sign-in was denied in the browser.")
+            raise AuthenticationError("The sign-in expired or failed. Run 'dataspring auth login' again.")
+        raise AuthenticationError("The sign-in timed out. Run 'dataspring auth login' again.")
+
+    async def store_key(self, key: str) -> "UserContext":
+        """``--key``: keep a key you already have (CI). The server says which org it is for."""
+        me = await self._me(key)
+        data = self._load()
+        self._add_profile(data, {"api_key": key, "key_id": None, "org_id": me["org_id"], "org_name": me.get("org_name")}, me.get("email"))
+        self._save(data)
+        return self._context(me)
+
+    # -- using the key ---------------------------------------------------
+
+    def get_access_token(self) -> str:
+        """The key this command sends: ``DATASPRING_API_KEY`` if set, else the
+        stored key for the org :meth:`resolve` names.
+
+        Raises:
+            Refused: not signed in, no org named among several, or a mismatch
+        """
+        return self.resolve().key
+
+    async def _me(self, key: str) -> dict:
+        async with httpx.AsyncClient(timeout=15.0) as client:
+            r = await client.get(f"{_host()}/api/me", headers={"Authorization": f"Bearer {key}"})
+        return self._me_answer(r)
+
+    @staticmethod
+    def _me_answer(r: httpx.Response) -> dict:
+        """``GET /api/me``'s body, or the refusal it answered with (D-99)."""
+        if r.status_code == 200:
+            return r.json()
+        try:
+            body = r.json()
+        except ValueError:
+            body = None
+        refusal = from_body(body)
+        if refusal is not None:
+            raise Refused(refusal.reason, refusal.note, refusal.fix)
+        if r.status_code == 401:
+            raise _not_signed_in("This key is unknown, revoked or expired.")
+        # ``note`` since tick 3sb, ``detail`` from older servers and FastAPI.
+        detail = (body.get("note") or body.get("detail")) if isinstance(body, dict) else None
+        if r.status_code == 403:
+            text = str(detail or "Access denied")
+            raise Refused(
+                classify(text) or "not_a_member", text,
+                "An owner or admin of the org fixes this at https://account.forspring.ai; "
+                "or run 'dataspring auth login' again.",
+            )
+        if r.status_code == 503:
+            raise Refused("account_unavailable", str(detail or "The Forspring account cannot be reached."),
+                          EN["account_unavailable"]["fix"])
+        raise AuthenticationError(f"Failed to resolve user context (HTTP {r.status_code})")
+
+    @staticmethod
+    def _context(me: dict) -> "UserContext":
+        org_id = me.get("org_id")
+        return UserContext(uid=me["uid"], email=me.get("email") or "", org_id=org_id,
+                           org_name=me.get("org_name") or org_id, role=me.get("org_role"))
+
+    async def get_user(self) -> "UserContext":
+        """The person and the key's org, as ``GET /api/me`` reports them."""
+        return self._context(await self._me(self.get_access_token()))
+
+    async def whoami(self) -> dict:
+        """D-99's ``whoami --json``: the person, the org, where the org came
+        from (:class:`ResolvedOrg`'s ``org_from``), the role."""
+        resolved = self.resolve()
+        me = await self._me(resolved.key)
+        out = {
+            "person": me.get("email"),
+            "org": me.get("org_id"),
+            "org_name": me.get("org_name"),
+            "org_from": resolved.org_from,
+            "role": me.get("org_role"),
+        }
+        if resolved.org_file:
+            out["org_file"] = resolved.org_file
+        return out
+
+    async def logout(self):
+        """Revoke every stored key on the server, then forget them."""
+        for profile in self.profiles().values():
+            if not profile.get("key_id"):
+                continue  # a --key key: not ours to revoke, just forgotten
+            try:
+                httpx.delete(f"{_host()}/api/keys/{profile['key_id']}",
+                             headers={"Authorization": f"Bearer {profile['api_key']}"}, timeout=10.0)
+            except httpx.HTTPError:
+                pass  # offline: revoke it from /api/keys later
+        if self.CREDENTIALS_FILE.exists():
+            self.CREDENTIALS_FILE.unlink()
+        if self.CONFIG_FILE.exists():
+            self.CONFIG_FILE.unlink()
+
+    def is_logged_in(self) -> bool:
+        """A key exists to use: ``DATASPRING_API_KEY`` or a stored one (which
+        one a command uses is :meth:`resolve`'s)."""
+        return bool(os.environ.get(ENV_KEY)) or bool(self.profiles())
+
+    def get_stored_email(self) -> str | None:
+        """Get stored email from config (doesn't validate the key)."""
+        return self._load_config().get("email")
+
+    def _save_config(self, data: dict):
+        """Save config data (non-sensitive)."""
+        existing = {}
+        if self.CONFIG_FILE.exists():
+            try:
+                existing = json.loads(self.CONFIG_FILE.read_text())
+            except json.JSONDecodeError:
+                pass
+        existing.update(data)
+        self.CONFIG_FILE.write_text(json.dumps(existing, indent=2))
+
+    def _load_config(self) -> dict:
+        """Load config data."""
+        if not self.CONFIG_FILE.exists():
+            return {}
+        try:
+            return json.loads(self.CONFIG_FILE.read_text())
+        except json.JSONDecodeError:
+            return {}
+
+
+# Global auth manager instance
+auth_manager = CLIAuthManager()

{dataspring_cli-0.4.1 → dataspring_cli-0.4.3}/cli/bundled_manifest.py

@@ -6,7 +6,7 @@ the server's to say whether the server has operations this CLI does not
 know. tests/test_skills_surface.py asserts it is current.
 """
 
-MANIFEST_HASH = "eacbe5d755f415a814b50b568eb105ff60693b92fe1ce44d30e39f71670d15d0"
+MANIFEST_HASH = "e61e4a47f3c193beb2f6d731efde82839f5e62788bfa18560277459487bb26a7"
 TOOL_KEYS = (
     "business_context_edit",
     "semantic_model_edit",