ermes-cli 1.0.0__py3-none-any.whl

ermes_cli/__init__.py

@@ -0,0 +1 @@
+__version__ = "1.0.0"

ermes_cli/admin_api.py

@@ -0,0 +1,285 @@
+"""Thin HTTP client for Ermes admin endpoints used during `ermes login`.
+
+Separate from `client.py` (which hits `/api/client/*` with a `sk_` key)
+because login bootstrapping uses a different auth shape: an Ermes admin
+JWT (minted by `/api/cli/exchange` after Auth0 device flow). The JWT
+lets us call `/api/admin/projects/all` to enumerate projects, and
+`/api/admin/projects/:id/cli-key` to provision this admin's key for a
+project on first use (`ermes use`, `ERMES_PROJECT`). The `keys` group also
+goes through the JWT since `/api/client/keys` no longer accepts sk_ keys.
+"""
+
+from __future__ import annotations
+
+import socket
+from dataclasses import dataclass
+from typing import Any
+
+import requests
+
+
+class AdminAPIError(Exception):
+    def __init__(self, message: str, status_code: int | None = None):
+        self.status_code = status_code
+        super().__init__(message)
+
+
+@dataclass(frozen=True)
+class ExchangeResult:
+    ermes_access_token: str
+    expires_at: str
+    admin_id: int
+    admin_email: str
+    organization_id: int
+    role: str
+
+
+@dataclass(frozen=True)
+class ProjectSummary:
+    id: int
+    name: str
+    role: str
+
+
+@dataclass(frozen=True)
+class ProjectKey:
+    id: int
+    name: str
+    value: str
+    scope: str
+    role: str
+
+
+def _post(url: str, json: dict, token: str | None = None, timeout: float = 15.0) -> Any:
+    headers = {"Content-Type": "application/json"}
+    if token:
+        headers["Authorization"] = f"Bearer {token}"
+    # No redirects: a 30x would re-send the bearer id_token to another host.
+    resp = requests.post(url, json=json, headers=headers, timeout=timeout, allow_redirects=False)
+    _raise_for_status(resp)
+    return resp.json() if resp.content else None
+
+
+def _get(
+    url: str, token: str, params: dict | None = None, timeout: float = 15.0
+) -> Any:
+    headers = {"Authorization": f"Bearer {token}"}
+    resp = requests.get(url, headers=headers, params=params, timeout=timeout, allow_redirects=False)
+    _raise_for_status(resp)
+    return resp.json() if resp.content else None
+
+
+def request(
+    method: str,
+    url: str,
+    token: str,
+    json: dict | None = None,
+    params: dict | None = None,
+    timeout: float = 15.0,
+) -> Any:
+    """Any admin-JWT call; the `keys` group uses it against /api/admin/projects/:id/keys."""
+    resp = requests.request(
+        method, url, json=json, params=params,
+        headers={"Authorization": f"Bearer {token}"}, timeout=timeout, allow_redirects=False,
+    )
+    _raise_for_status(resp)
+    return resp.json() if resp.content else None
+
+
+def _raise_for_status(resp: requests.Response) -> None:
+    if 300 <= resp.status_code < 400:
+        # Redirects are not followed (the bearer would be re-sent elsewhere), and a
+        # 30x body is not the JSON the callers expect: name it instead of a TypeError.
+        raise AdminAPIError(
+            f"unexpected redirect to {resp.headers.get('Location', '?')}; refusing to resend credentials",
+            resp.status_code,
+        )
+    if resp.status_code >= 400:
+        try:
+            body = resp.json()
+            message = body.get("message") or body.get("error") or resp.text[:300]
+            code = body.get("code")
+            detail = f"{message} (code={code})" if code else message
+        except ValueError:
+            detail = resp.text[:300] or f"HTTP {resp.status_code}"
+        raise AdminAPIError(detail, resp.status_code)
+
+
+# ---------------------------------------------------------------------------
+# /api/cli/exchange
+# ---------------------------------------------------------------------------
+
+
+def exchange_auth0_token(
+    base_url: str,
+    auth0_access_token: str,
+    id_token: str | None = None,
+) -> ExchangeResult:
+    """Trade an Auth0 access token for an Ermes admin JWT.
+
+    `id_token` is optional. Sending it lets the platform fall back to the
+    id_token's `email` claim when the access_token doesn't carry one
+    (Auth0's default behavior, absent a custom Action). Audience pinning
+    on the platform side keeps this safe: the id_token must be issued for
+    the same Auth0 client_id that minted the access_token.
+
+    Maps platform error codes (1009-1013) to actionable AdminAPIError
+    messages so the CLI can give the user a clear next step rather than a
+    raw HTTP code.
+    """
+    url = f"{base_url.rstrip('/')}/api/cli/exchange"
+    payload: dict = {"access_token": auth0_access_token}
+    if id_token:
+        payload["id_token"] = id_token
+    try:
+        body = _post(url, payload)
+    except AdminAPIError as exc:
+        # Re-frame known platform error codes for the CLI user.
+        if exc.status_code == 404 and "1009" in str(exc):
+            raise AdminAPIError(
+                "Ermes server doesn't have CLI exchange enabled "
+                "(AUTH_CLI_AUDIENCE not set on the API). Ask your ops team.",
+                exc.status_code,
+            ) from exc
+        if exc.status_code == 403 and "1013" in str(exc):
+            raise AdminAPIError(
+                "Your Auth0 email is not verified. Open the verification email "
+                "from Auth0, confirm it, then run `ermes login` again.",
+                exc.status_code,
+            ) from exc
+        if exc.status_code == 403 and "1012" in str(exc):
+            raise AdminAPIError(
+                "Authenticated, but no Ermes admin account exists for this email. "
+                "Ask an organization owner to invite you in the Ermes UI first.",
+                exc.status_code,
+            ) from exc
+        raise
+
+    return ExchangeResult(
+        ermes_access_token=body["access_token"],
+        expires_at=body["expires_at"],
+        admin_id=body["admin"]["id"],
+        admin_email=body["admin"]["email"],
+        organization_id=body["admin"]["organization_id"],
+        role=body["admin"]["role"],
+    )
+
+
+# ---------------------------------------------------------------------------
+# /api/admin/projects/all + /api/admin/projects/:id/keys
+# ---------------------------------------------------------------------------
+
+
+def list_all_projects(base_url: str, ermes_jwt: str) -> list[ProjectSummary]:
+    """Enumerate every project the authenticated admin can access."""
+    url = f"{base_url.rstrip('/')}/api/admin/projects/all"
+    data = _get(url, ermes_jwt)
+    # Endpoint returns a flat list per ProjectController.allProjects.
+    projects: list[ProjectSummary] = []
+    for p in data or []:
+        projects.append(
+            ProjectSummary(
+                id=int(p["id"]),
+                name=str(p.get("name") or p["id"]),
+                role=str(p.get("role") or "admin"),
+            )
+        )
+    return projects
+
+
+def list_project_keys(
+    base_url: str, ermes_jwt: str, project_id: int
+) -> list[ProjectKey]:
+    """List all (non-deleted) API keys for one project."""
+    url = f"{base_url.rstrip('/')}/api/admin/projects/{project_id}/keys"
+    # `pagedApiKeys` returns `{results: [...], total, ...}`; the page size param is
+    # `limit` (searchParamsSchema, default 25), so ask for one big page explicitly.
+    data = _get(url, ermes_jwt, params={"limit": 200})
+    if isinstance(data, dict) and "results" in data:
+        items = data["results"]
+    elif isinstance(data, list):
+        items = data
+    else:
+        items = []
+    return [
+        ProjectKey(
+            id=int(item["id"]),
+            name=str(item.get("name") or ""),
+            value=str(item.get("value") or ""),
+            scope=str(item.get("scope") or ""),
+            role=str(item.get("role") or ""),
+        )
+        for item in items
+    ]
+
+
+def create_project_key(
+    base_url: str,
+    ermes_jwt: str,
+    project_id: int,
+    name: str,
+    scope: str = "secret",
+    role: str = "admin",
+) -> ProjectKey:
+    """Mint a new sk_/pk_ key for one project."""
+    url = f"{base_url.rstrip('/')}/api/admin/projects/{project_id}/keys"
+    body = _post(
+        url,
+        {"name": name, "scope": scope, "role": role},
+        token=ermes_jwt,
+    )
+    return ProjectKey(
+        id=int(body["id"]),
+        name=str(body.get("name") or ""),
+        value=str(body.get("value") or ""),
+        scope=str(body.get("scope") or ""),
+        role=str(body.get("role") or ""),
+    )
+
+
+def create_project(
+    base_url: str,
+    ermes_jwt: str,
+    name: str,
+    timezone: str,
+    locale: str,
+    description: str | None = None,
+) -> ProjectSummary:
+    """Create a new project in the authenticated admin's organization.
+
+    POST /api/admin/projects. Requires the caller's org role to be `admin`
+    or `owner` (the platform enforces this; a `member` gets a 403 that
+    surfaces here as an AdminAPIError). The creating admin is automatically
+    added as a project admin server-side, so the returned summary's role is
+    always "admin".
+    """
+    url = f"{base_url.rstrip('/')}/api/admin/projects"
+    payload: dict = {"name": name, "timezone": timezone, "locale": locale}
+    if description is not None:
+        payload["description"] = description
+    body = _post(url, payload, token=ermes_jwt)
+    return ProjectSummary(
+        id=int(body["id"]),
+        name=str(body.get("name") or name),
+        role="admin",
+    )
+
+
+def create_cli_key(
+    base_url: str, ermes_jwt: str, project_id: int, hostname: str | None = None
+) -> ProjectKey:
+    """Find-or-create THIS admin's CLI key for one project (DEV-2259).
+
+    `POST /api/admin/projects/:id/cli-key` binds the key to the calling admin
+    and to the hostname, so removing the admin from the project revokes it and
+    two admins on the same host never share a key.
+    """
+    url = f"{base_url.rstrip('/')}/api/admin/projects/{project_id}/cli-key"
+    body = _post(url, {"hostname": hostname or socket.gethostname()}, token=ermes_jwt)
+    return ProjectKey(
+        id=int(body["id"]),
+        name=str(body.get("name") or ""),
+        value=str(body.get("value") or ""),
+        scope=str(body.get("scope") or ""),
+        role=str(body.get("role") or ""),
+    )

ermes_cli/auth0.py

@@ -0,0 +1,220 @@
+"""Auth0 Device Authorization Flow (RFC 8628) for ermes-cli.
+
+Same tenant as publinker-cli (`dev-hqiwr-re.us.auth0.com`) so the
+authenticated user is the same identity across both tools. Different
+native application + different API audience so tokens issued for
+publinker can't be used against the Ermes API and vice versa.
+
+Three operations:
+- `device_login()` — full RFC 8628 flow end-to-end; returns a TokenBundle.
+- `request_device_code()` / `poll_for_token()` — split for granular tests.
+- `refresh_access_token(refresh_token)` — exchange a refresh token for a new
+  access token (Auth0 rotates the refresh token; we carry the old one
+  forward if the response omits a new one).
+
+All three are pure: no keychain writes. The caller decides what to persist.
+"""
+
+from __future__ import annotations
+
+import time
+import webbrowser
+from dataclasses import dataclass
+from typing import Callable, Optional
+
+import requests
+
+from ermes_cli.keyring_store import TokenBundle
+
+# Static Auth0 config. These values are non-secret per OAuth spec — the
+# client_id of a public Native client and the API audience are public.
+# Same tenant as publinker-cli (one Auth0 user identity across both tools);
+# different client_id + audience so Ermes and publinker can't cross-use tokens.
+AUTH0_DOMAIN = "dev-hqiwr-re.us.auth0.com"
+AUTH0_CLIENT_ID = "tV4eZi7ZGXbSdfanxWA9OyIDdYcDwpnv"
+AUTH0_AUDIENCE = "https://ermes.publinker.com/api"
+AUTH0_SCOPES = "openid profile email offline_access"
+
+
+@dataclass(frozen=True)
+class Auth0Config:
+    domain: str = AUTH0_DOMAIN
+    client_id: str = AUTH0_CLIENT_ID
+    audience: str = AUTH0_AUDIENCE
+    scopes: str = AUTH0_SCOPES
+
+    @property
+    def device_code_url(self) -> str:
+        return f"https://{self.domain}/oauth/device/code"
+
+    @property
+    def token_url(self) -> str:
+        return f"https://{self.domain}/oauth/token"
+
+    @property
+    def revoke_url(self) -> str:
+        return f"https://{self.domain}/oauth/revoke"
+
+
+def auth0_config() -> Auth0Config:
+    return Auth0Config()
+
+
+class AuthError(Exception):
+    """Raised when the Auth0 flow fails terminally (user denied, expired, server error)."""
+
+
+@dataclass(frozen=True)
+class DeviceCode:
+    device_code: str
+    user_code: str
+    verification_uri_complete: str
+    expires_in: int  # seconds
+    interval: int  # poll seconds
+
+
+def request_device_code(cfg: Optional[Auth0Config] = None) -> DeviceCode:
+    """Step 1 of RFC 8628 — request a device code from Auth0."""
+    cfg = cfg or auth0_config()
+    resp = requests.post(
+        cfg.device_code_url,
+        data={
+            "client_id": cfg.client_id,
+            "scope": cfg.scopes,
+            "audience": cfg.audience,
+        },
+        headers={"Content-Type": "application/x-www-form-urlencoded"},
+        timeout=10,
+    )
+    if resp.status_code != 200:
+        raise AuthError(
+            f"device code request failed: {resp.status_code} {resp.text}"
+        )
+    body = resp.json()
+    return DeviceCode(
+        device_code=body["device_code"],
+        user_code=body["user_code"],
+        verification_uri_complete=body["verification_uri_complete"],
+        expires_in=int(body["expires_in"]),
+        interval=int(body["interval"]),
+    )
+
+
+def poll_for_token(
+    device_code: DeviceCode,
+    cfg: Optional[Auth0Config] = None,
+    sleep: Callable[[float], None] = time.sleep,
+    now: Callable[[], float] = time.monotonic,
+) -> TokenBundle:
+    """Step 2 of RFC 8628 — poll the token endpoint until the user authorizes
+    or the device code expires.
+
+    `sleep` and `now` are injectable so tests can run without real-time waits.
+    """
+    cfg = cfg or auth0_config()
+    interval = device_code.interval
+    deadline = now() + device_code.expires_in
+
+    while now() < deadline:
+        sleep(interval)
+        resp = requests.post(
+            cfg.token_url,
+            data={
+                "grant_type": "urn:ietf:params:oauth:grant-type:device_code",
+                "device_code": device_code.device_code,
+                "client_id": cfg.client_id,
+            },
+            headers={"Content-Type": "application/x-www-form-urlencoded"},
+            timeout=10,
+        )
+        if resp.status_code == 200:
+            return TokenBundle.from_token_response(resp.json())
+
+        try:
+            err = resp.json().get("error", "")
+        except ValueError:
+            err = ""
+
+        if err == "authorization_pending":
+            continue
+        if err == "slow_down":
+            interval += 5
+            continue
+        if err in {"access_denied", "expired_token"}:
+            raise AuthError(f"login failed: {err}")
+        raise AuthError(
+            f"unexpected token endpoint response {resp.status_code}: {resp.text}"
+        )
+
+    raise AuthError("device code expired before user completed login")
+
+
+def refresh_access_token(
+    refresh_token: str, cfg: Optional[Auth0Config] = None
+) -> TokenBundle:
+    """Exchange a refresh token for a new access token (and rotated refresh token).
+
+    Auth0 rotates refresh tokens by default — the response may carry a NEW
+    refresh_token, or (rarely) reuse the old one. Carry forward the prior
+    refresh token if the response omits it, so the caller never loses the
+    ability to refresh again.
+    """
+    cfg = cfg or auth0_config()
+    resp = requests.post(
+        cfg.token_url,
+        data={
+            "grant_type": "refresh_token",
+            "client_id": cfg.client_id,
+            "refresh_token": refresh_token,
+        },
+        headers={"Content-Type": "application/x-www-form-urlencoded"},
+        timeout=10,
+    )
+    if resp.status_code != 200:
+        raise AuthError(f"refresh failed: {resp.status_code} {resp.text}")
+    body = resp.json()
+    if "refresh_token" not in body:
+        body["refresh_token"] = refresh_token
+    return TokenBundle.from_token_response(body)
+
+
+def device_login(
+    cfg: Optional[Auth0Config] = None,
+    open_browser: bool = True,
+    on_user_code: Optional[Callable[[DeviceCode], None]] = None,
+) -> TokenBundle:
+    """Run the full RFC 8628 device flow end-to-end. Returns the new token bundle.
+
+    `on_user_code` is invoked with the device code so the caller can print the
+    user_code + verification URL. If `open_browser` is True the verification URL
+    is also opened in the default browser.
+    """
+    code = request_device_code(cfg)
+    if on_user_code is not None:
+        on_user_code(code)
+    if open_browser:
+        try:
+            webbrowser.open(code.verification_uri_complete)
+        except Exception:
+            # Browser open is best-effort — headless/SSH sessions won't have one.
+            pass
+    return poll_for_token(code, cfg)
+
+
+def revoke_refresh_token(
+    refresh_token: str, cfg: Optional[Auth0Config] = None
+) -> bool:
+    """Best-effort RFC 7009 revocation on logout, so a refresh token copied out of
+    the vault is dead server-side too. Never raises: logout must still clear the
+    local copy when Auth0 is unreachable."""
+    cfg = cfg or auth0_config()
+    try:
+        resp = requests.post(
+            cfg.revoke_url,
+            data={"client_id": cfg.client_id, "token": refresh_token},
+            headers={"Content-Type": "application/x-www-form-urlencoded"},
+            timeout=10,
+        )
+    except requests.RequestException:
+        return False
+    return resp.status_code == 200

ermes_cli/client.py

@@ -0,0 +1,100 @@
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+# Re-export ErmesAPIError from errors.py so existing `from ermes_cli.client
+# import ErmesAPIError` keeps working without touching every command file.
+from ermes_cli.config import validate_api_key
+from ermes_cli.errors import ErmesAPIError, WriteBlockedError  # noqa: F401
+from ermes_cli.write_mode import assert_writes_allowed
+
+_ERROR_MESSAGES = {
+    401: "Invalid API key or expired token",
+    403: "Insufficient permissions",
+    404: "Resource not found",
+}
+
+
+class ErmesClient:
+    def __init__(self, base_url: str, api_key: str, timeout: float = 30.0):
+        # Every key tier (env, projects.yml, config.yml) lands here: an invalid
+        # header value would otherwise surface as an httpx error echoing the key.
+        api_key = validate_api_key(api_key)
+        self._base_url = base_url.rstrip("/") + "/api/client"
+        self._client = httpx.Client(
+            base_url=self._base_url,
+            headers={"Authorization": f"Bearer {api_key}"},
+            timeout=timeout,
+        )
+
+    def _handle_response(self, response: httpx.Response) -> Any:
+        if response.is_success:
+            if response.status_code == 204:
+                return None
+            content_type = response.headers.get("content-type", "")
+            if "application/json" in content_type:
+                return response.json()
+            return response.text or None
+        status = response.status_code
+        if status in _ERROR_MESSAGES:
+            raise ErmesAPIError(_ERROR_MESSAGES[status], status)
+        if status == 422:
+            try:
+                body = response.json()
+                detail = body.get("error") or body.get("message") or str(body)
+            except Exception:
+                detail = response.text
+            raise ErmesAPIError(f"Validation error: {detail}", status)
+        raise ErmesAPIError(f"Server error: {status}", status)
+
+    def get(self, path: str, params: dict | None = None) -> Any:
+        response = self._client.get(path, params=params)
+        return self._handle_response(response)
+
+    def post(self, path: str, json: dict | None = None) -> Any:
+        assert_writes_allowed("POST", path)
+        response = self._client.post(path, json=json)
+        return self._handle_response(response)
+
+    def patch(self, path: str, json: dict | None = None) -> Any:
+        assert_writes_allowed("PATCH", path)
+        response = self._client.patch(path, json=json)
+        return self._handle_response(response)
+
+    def put(self, path: str, json: dict | None = None) -> Any:
+        assert_writes_allowed("PUT", path)
+        response = self._client.put(path, json=json)
+        return self._handle_response(response)
+
+    def delete(self, path: str) -> Any:
+        assert_writes_allowed("DELETE", path)
+        response = self._client.delete(path)
+        return self._handle_response(response)
+
+    MAX_PAGES = 500
+
+    def get_paginated(
+        self, path: str, params: dict | None = None, limit: int = 100
+    ) -> list[dict]:
+        params = dict(params or {})
+        all_results: list[dict] = []
+        for _page in range(self.MAX_PAGES):
+            data = self.get(path, params=params)
+            if not isinstance(data, dict) or "results" not in data:
+                return [data] if data else []
+            all_results.extend(data["results"])
+            if limit > 0 and len(all_results) >= limit:
+                return all_results[:limit]
+            next_cursor = data.get("nextCursor")
+            if not next_cursor:
+                return all_results
+            params["cursor"] = next_cursor
+            params["page"] = "next"
+        import sys
+        print(f"Warning: get_paginated hit max page limit ({self.MAX_PAGES}) for {path}", file=sys.stderr)
+        return all_results
+
+    def close(self) -> None:
+        self._client.close()