glossa-cli 0.1.0__3-py3-none-any.whl

glossa_cli/__init__.py

@@ -0,0 +1,7 @@
+"""Glossa CLI — a standalone terminal client for the Glossa REST API.
+
+Talks to the API over HTTP using the same auth as the MCP server
+(``GLOSSA_API_TOKEN`` static token or OAuth device-code flow). Install with::
+
+    uv tool install glossa-cli      # or: pipx install glossa-cli / uvx glossa-cli
+"""

glossa_cli/auth.py

@@ -0,0 +1,227 @@
+"""OAuth 2.0 Device-Code flow + credential storage for the Glossa CLI.
+
+Vendored from ``backend/glossa_mcp/auth.py`` so the CLI ships as a standalone,
+lightweight package (httpx + stdlib only) without depending on the heavy
+``glossa-backend`` distribution.
+
+Design:
+- Credentials are stored in ``~/.config/glossa/credentials.json`` (shared with
+  the MCP client — a token approved once works for both).
+- When a valid access token exists it's used directly.
+- When the access token has expired the refresh token is used to get a new pair.
+- When there are no credentials at all, the device-code flow is initiated:
+    1. POST /api/oauth/device_authorization → get device_code + user_code
+    2. Print verification_uri_complete to stderr so the user can approve it.
+    3. Poll /api/oauth/token every ``interval`` seconds until approved, denied
+       or the device code expires.
+    4. Save the resulting access + refresh tokens to disk.
+
+Only ``ensure_token(base_url)`` is the public entry-point — it returns a valid
+Bearer token string or raises ``AuthError`` (fatal, surfaced to the user).
+"""
+
+import asyncio
+import json
+import sys
+import time
+from dataclasses import asdict, dataclass
+from pathlib import Path
+
+import httpx
+
+# ── Configuration ─────────────────────────────────────────────────────────────
+
+CREDENTIALS_PATH = Path.home() / ".config" / "glossa" / "credentials.json"
+POLL_MAX_SECONDS = 600  # 10 min — matches backend DEVICE_CODE_TTL
+DEFAULT_POLL_INTERVAL = 5  # seconds between /token poll attempts
+
+
+# ── Data ─────────────────────────────────────────────────────────────────────
+
+
+@dataclass
+class Credentials:
+    access_token: str
+    refresh_token: str
+    expires_at: float  # Unix timestamp when access_token expires
+    base_url: str
+
+    def access_expired(self) -> bool:
+        # Give a 30-second buffer so we refresh before the token actually expires.
+        return time.time() >= (self.expires_at - 30)
+
+
+# ── Storage ──────────────────────────────────────────────────────────────────
+
+
+def _load() -> Credentials | None:
+    if not CREDENTIALS_PATH.exists():
+        return None
+    try:
+        data = json.loads(CREDENTIALS_PATH.read_text())
+        return Credentials(**data)
+    except Exception:
+        return None
+
+
+def _save(creds: Credentials) -> None:
+    CREDENTIALS_PATH.parent.mkdir(parents=True, exist_ok=True)
+    CREDENTIALS_PATH.write_text(json.dumps(asdict(creds), indent=2))
+
+
+def _clear() -> None:
+    if CREDENTIALS_PATH.exists():
+        CREDENTIALS_PATH.unlink()
+
+
+def clear_credentials() -> bool:
+    """Remove any cached OAuth credentials. Returns True if a file was removed."""
+    existed = CREDENTIALS_PATH.exists()
+    _clear()
+    return existed
+
+
+# ── Errors ───────────────────────────────────────────────────────────────────
+
+
+class AuthError(Exception):
+    """Fatal auth failure — message is user-visible."""
+
+
+# ── OAuth HTTP helpers ────────────────────────────────────────────────────────
+
+
+async def _post(client: httpx.AsyncClient, path: str, body: dict) -> dict:
+    resp = await client.post(path, json=body)
+    try:
+        payload = resp.json()
+    except Exception:
+        payload = {}
+    if resp.is_success:
+        return payload
+    # Surface OAuth error_description if present
+    detail = payload.get("detail") or {}
+    if isinstance(detail, dict):
+        msg = detail.get("error_description") or detail.get("error") or str(payload)
+    elif isinstance(detail, str):
+        msg = detail
+    else:
+        msg = resp.text or resp.reason_phrase
+    raise httpx.HTTPStatusError(msg, request=resp.request, response=resp)
+
+
+async def _refresh(client: httpx.AsyncClient, refresh_token: str, base_url: str) -> Credentials:
+    data = await _post(client, "/api/oauth/token", {
+        "grant_type": "refresh_token",
+        "refresh_token": refresh_token,
+    })
+    return Credentials(
+        access_token=data["access_token"],
+        refresh_token=data["refresh_token"],
+        expires_at=time.time() + data.get("expires_in", 3600),
+        base_url=base_url,
+    )
+
+
+# ── Device-code flow ─────────────────────────────────────────────────────────
+
+
+async def _device_flow(base_url: str) -> Credentials:
+    """Run the full RFC 8628 device-code flow interactively (via stderr)."""
+    async with httpx.AsyncClient(base_url=base_url, timeout=30) as client:
+        # 1 — Request codes
+        init = await _post(client, "/api/oauth/device_authorization", {})
+        device_code = init["device_code"]
+        user_code = init["user_code"]
+        verification_uri_complete = init["verification_uri_complete"]
+        interval = int(init.get("interval", DEFAULT_POLL_INTERVAL))
+
+        # 2 — Prompt user (stderr keeps stdout clean for piping / JSON output)
+        print(
+            f"\n{'─' * 60}\n"
+            f"  Glossa CLI — authorisation required\n\n"
+            f"  1. Open this URL in your browser:\n"
+            f"     {verification_uri_complete}\n\n"
+            f"  2. Code to confirm: {user_code}\n"
+            f"{'─' * 60}\n",
+            file=sys.stderr,
+            flush=True,
+        )
+
+        # 3 — Poll
+        deadline = time.time() + POLL_MAX_SECONDS
+        while time.time() < deadline:
+            await asyncio.sleep(interval)
+            try:
+                data = await _post(client, "/api/oauth/token", {
+                    "grant_type": "urn:ietf:params:oauth:grant-type:device_code",
+                    "device_code": device_code,
+                })
+                # Success
+                print("  ✓ Authorised — Glossa CLI is ready.\n", file=sys.stderr, flush=True)
+                return Credentials(
+                    access_token=data["access_token"],
+                    refresh_token=data["refresh_token"],
+                    expires_at=time.time() + data.get("expires_in", 3600),
+                    base_url=base_url,
+                )
+            except httpx.HTTPStatusError as exc:
+                # Parse the body that _post embeds in the exception message
+                try:
+                    body = exc.response.json()
+                    detail = body.get("detail", {})
+                    error_code = detail.get("error") if isinstance(detail, dict) else None
+                except Exception:
+                    error_code = None
+
+                if error_code == "authorization_pending":
+                    continue  # keep polling
+                if error_code == "slow_down":
+                    interval += 5
+                    continue
+                if error_code in ("access_denied", "expired_token", "invalid_grant"):
+                    # Upgrade path: surface the upgrade URL if present
+                    upgrade_url = (
+                        (detail or {}).get("upgrade_url") if isinstance(detail, dict) else None
+                    )
+                    if upgrade_url:
+                        raise AuthError(
+                            f"Glossa access requires a Pro subscription.\n"
+                            f"Upgrade at: {upgrade_url}"
+                        ) from exc
+                    raise AuthError(f"Authorisation denied ({error_code}).") from exc
+                # Unknown error — surface verbatim
+                raise AuthError(f"Token error: {exc}") from exc
+
+        raise AuthError("Authorisation timed out — please run the command again.")
+
+
+# ── Public entry-point ────────────────────────────────────────────────────────
+
+
+async def ensure_token(base_url: str) -> str:
+    """Return a valid Bearer token for *base_url*, refreshing or re-authorising as needed."""
+    creds = _load()
+
+    # Mismatched base_url (e.g. switched from prod to dev) — start fresh
+    if creds is not None and creds.base_url.rstrip("/") != base_url.rstrip("/"):
+        _clear()
+        creds = None
+
+    if creds is not None and not creds.access_expired():
+        return creds.access_token
+
+    if creds is not None and creds.refresh_token:
+        try:
+            async with httpx.AsyncClient(base_url=base_url, timeout=30) as client:
+                creds = await _refresh(client, creds.refresh_token, base_url)
+            _save(creds)
+            return creds.access_token
+        except Exception:
+            # Refresh failed (revoked / expired / downgraded) — full re-auth
+            _clear()
+
+    # No usable credentials — run device-code flow
+    creds = await _device_flow(base_url)
+    _save(creds)
+    return creds.access_token