ermes-cli 1.0.0__py3-none-any.whl

ermes_cli/keyring_store.py

@@ -0,0 +1,145 @@
+"""Cross-platform OS-vault token storage via `keyring`.
+
+macOS   → Keychain
+Linux   → secret-service (GNOME Keyring, KWallet), falls back to encrypted
+          file via `keyring`'s file backend
+Windows → Credential Manager
+
+The whole token bundle (access + refresh + id + expires_at) is stored as a
+single JSON blob under one keyring item. One read/write per operation —
+simpler than splitting across three items, and atomic from the OS vault's
+perspective.
+
+This module ONLY deals with Auth0 tokens. Per-project Ermes API keys live
+in `~/.ermes/projects.yml` (managed by `config.py`); they're project-scoped
+non-bearer secrets that the user can already regenerate from the Ermes UI,
+so the marginal value of keychain storage there is low.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+import time
+from dataclasses import asdict, dataclass
+from typing import Optional
+
+import keyring
+import keyring.errors
+
+from ermes_cli.config import _config_dir, _open_private
+
+KEYRING_SERVICE = "ermes-cli"
+KEYRING_ACCOUNT = "default"
+
+
+def _fallback_path():
+    """Headless Linux / containers have no OS vault: keyring raises
+    `NoKeyringError`. Fall back to a 0600 file next to projects.yml (which
+    already holds sk_ keys with the same protection)."""
+    return _config_dir() / "auth0-tokens.json"
+
+
+@dataclass
+class TokenBundle:
+    access_token: str
+    refresh_token: str
+    id_token: str
+    expires_at: int  # unix epoch seconds
+    base_url: str = ""  # the Ermes host these tokens were obtained for (DEV-2261)
+
+    @classmethod
+    def from_token_response(
+        cls, body: dict, now: Optional[int] = None
+    ) -> "TokenBundle":
+        """Build a bundle from Auth0's `/oauth/token` response."""
+        now = now if now is not None else int(time.time())
+        return cls(
+            access_token=body["access_token"],
+            refresh_token=body.get("refresh_token", ""),
+            id_token=body.get("id_token", ""),
+            expires_at=now + int(body.get("expires_in", 0)),
+        )
+
+    def is_expired(self, now: Optional[int] = None, leeway: int = 60) -> bool:
+        """True if the access token has expired (with `leeway` seconds buffer)."""
+        now = now if now is not None else int(time.time())
+        return now + leeway >= self.expires_at
+
+
+# keyring's no-op / always-failing stand-ins and the `keyrings.alt` plaintext
+# backends: a token "saved" there is silently lost or written world-readable.
+_NOT_A_VAULT = ("keyring.backends.null", "keyring.backends.fail", "keyrings.alt")
+_warned_fallback = False
+
+
+def _vault_is_real() -> bool:
+    return not type(keyring.get_keyring()).__module__.startswith(_NOT_A_VAULT)
+
+
+def save(bundle: TokenBundle) -> None:
+    """Exactly one store holds the bundle afterwards: the vault, or (when it is
+    missing, fake or refusing) the 0600 fallback file."""
+    raw = json.dumps(asdict(bundle))
+    if _vault_is_real():
+        try:
+            keyring.set_password(KEYRING_SERVICE, KEYRING_ACCOUNT, raw)
+            _fallback_path().unlink(missing_ok=True)
+            return
+        except keyring.errors.KeyringError:
+            pass
+    global _warned_fallback
+    if not _warned_fallback:
+        _warned_fallback = True
+        print(
+            f"warning: no usable OS keyring; Auth0 tokens stored in {_fallback_path()} (mode 0600)",
+            file=sys.stderr,
+        )
+    path = _fallback_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with _open_private(path) as f:
+        f.write(raw)
+    try:  # never leave an older bundle behind in the vault
+        keyring.delete_password(KEYRING_SERVICE, KEYRING_ACCOUNT)
+    except keyring.errors.KeyringError:
+        pass
+
+
+def load() -> Optional[TokenBundle]:
+    # The fallback file exists only when the last save() could not use the vault,
+    # so when both are present the file is the newer copy.
+    path = _fallback_path()
+    raw = path.read_text() if path.exists() else None
+    if not raw:
+        try:
+            raw = keyring.get_password(KEYRING_SERVICE, KEYRING_ACCOUNT)
+        except keyring.errors.KeyringError:
+            raw = None
+    if not raw:
+        return None
+    try:
+        data = json.loads(raw)
+        return TokenBundle(**data)
+    except (json.JSONDecodeError, TypeError, KeyError):
+        # Corrupted entry — treat as logged out. The next login overwrites it.
+        return None
+
+
+def clear() -> None:
+    """Remove the stored tokens. Raises `keyring.errors.KeyringError` when the
+    backend refuses the delete, so `logout` cannot report success while the
+    token is still in the vault. Absent entry / no vault = already cleared."""
+    try:
+        keyring.delete_password(KEYRING_SERVICE, KEYRING_ACCOUNT)
+    except keyring.errors.NoKeyringError:
+        pass
+    except keyring.errors.PasswordDeleteError as exc:
+        # macOS wraps EVERY SecItemDelete failure (locked vault included) in this,
+        # not just "no such item": only a confirmed-absent entry counts as cleared.
+        try:
+            still_there = keyring.get_password(KEYRING_SERVICE, KEYRING_ACCOUNT)
+        except keyring.errors.NoKeyringError:
+            still_there = None
+        if still_there is not None:
+            raise keyring.errors.KeyringError(f"token still in the vault after delete: {exc}") from exc
+    _fallback_path().unlink(missing_ok=True)

ermes_cli/main.py

@@ -0,0 +1,193 @@
+from __future__ import annotations
+import atexit
+from typing import Optional
+import typer
+from ermes_cli import __version__
+from ermes_cli.config import resolve_profile, ConfigError
+from ermes_cli.client import ErmesClient
+
+app = typer.Typer(
+    name="ermes",
+    help="CLI for managing Ermes marketing automation APIs",
+    no_args_is_help=True,
+)
+
+
+class State:
+    profile_name: str | None = None
+    use_json: bool = False
+    client: ErmesClient | None = None
+
+
+state = State()
+
+
+def _close_client():
+    if state.client is not None:
+        state.client.close()
+
+
+atexit.register(_close_client)
+
+
+@app.callback()
+def main(
+    profile: Optional[str] = typer.Option(None, "--profile", "-p", help="Profile name"),
+    use_json: bool = typer.Option(False, "--json", help="Output as JSON"),
+):
+    state.profile_name = profile
+    state.use_json = use_json
+
+
+def get_client() -> ErmesClient:
+    if state.client is None:
+        try:
+            profile = resolve_profile(state.profile_name)
+            state.client = ErmesClient(base_url=profile["base_url"], api_key=profile["api_key"])
+        except ConfigError as e:  # also a malformed key from projects.yml / config.yml
+            typer.echo(str(e), err=True)
+            raise typer.Exit(code=1) from e
+    return state.client
+
+
+@app.command()
+def version():
+    """Show CLI version."""
+    if state.use_json:
+        import json
+
+        print(json.dumps({"version": __version__}))
+    else:
+        typer.echo(f"ermes-cli {__version__}")
+
+
+@app.command()
+def whoami(
+    check: bool = typer.Option(
+        False, "--check", help="Also make one authenticated API read to prove the key works."
+    ),
+):
+    """Show the Auth0 identity, active project, API base URL, and write-mode state."""
+    from ermes_cli.output import render_detail
+    from ermes_cli.config import (
+        get_auth0_email,
+        get_base_url,
+        get_effective_project,
+        mask_key,
+    )
+    from ermes_cli import write_mode
+
+    email = get_auth0_email()
+    # Must match what `resolve_profile()` will pick across ALL of its tiers — `--profile` and
+    # ERMES_PROFILE included, not just ERMES_PROJECT — otherwise whoami reports one project
+    # while every data command queries another.
+    active_id, active, project_source = get_effective_project(state.profile_name)
+    ws = write_mode.status()
+
+    # `project_source` belongs in BOTH branches: the whole point is that the origin of the
+    # project is always visible, and the legacy/unresolved paths are exactly where it is
+    # least obvious.
+    result: dict = {
+        "base_url": get_base_url(),
+        "auth0_email": email,
+        "project_source": project_source,
+        "writes_allowed": ws["allowed"],
+        "writes_mode": ws["mode"],
+        "writes_until": ws["until"] or "(n/a)",
+    }
+
+    if active and active_id is not None:
+        result.update({
+            "active_project_id": active_id,
+            "active_project_name": active.get("name"),
+            "active_project_role": active.get("role"),
+            "api_key": mask_key(active["api_key"]) if active.get("api_key") else "(provisioned on first use)",
+        })
+        if check:
+            result["api_check"] = _api_check()
+        render_detail(result, use_json=state.use_json)
+        return
+
+    # An unresolvable override is a config error, not a legacy-profile setup. Say what whoami
+    # resolved before resolve_profile() raises, so the diagnosis and the fix hint both land.
+    if "NOT FOUND" in project_source:
+        typer.echo(f"whoami: {project_source}", err=True)
+
+    # Legacy profile path — hit the API to confirm liveness.
+    try:
+        profile = resolve_profile(state.profile_name)
+    except ConfigError as e:
+        typer.echo(str(e), err=True)
+        raise typer.Exit(code=1)
+    client = ErmesClient(base_url=profile["base_url"], api_key=profile["api_key"])
+    try:
+        project_info = client.get("/")
+    except Exception as e:
+        # Never echo the exception text: an httpx header error repeats the key verbatim.
+        typer.echo(f"Connection failed: {type(e).__name__}", err=True)
+        raise typer.Exit(code=1)
+    finally:
+        client.close()
+    result["profile"] = state.profile_name or "(default)"
+    result["base_url"] = profile["base_url"]
+    result["api_key"] = mask_key(profile["api_key"])
+    if isinstance(project_info, dict):
+        result.update(project_info)
+    if check:
+        result["api_check"] = _api_check()
+    render_detail(result, use_json=state.use_json)
+
+
+def _api_check() -> str:
+    """One bounded read with the resolved key; exit 1 so scripts can gate on it.
+
+    Probes `/` (the project info route every role can read) rather than
+    `/campaigns`, which is editor-gated and fails for support-role keys.
+    """
+    client = get_client()  # a ConfigError already printed its own message + Exit(1)
+    try:
+        client.get("/")
+    except Exception as e:  # noqa: BLE001 — any failure is a failed check; never echo the key
+        typer.echo(f"api_check failed: {type(e).__name__}", err=True)
+        raise typer.Exit(code=1)
+    return "ok"
+
+
+# Register subcommands
+from ermes_cli.commands.campaigns import campaigns_app
+from ermes_cli.commands.templates import templates_app
+from ermes_cli.commands.users import users_app
+from ermes_cli.commands.config_cmd import config_app
+from ermes_cli.commands.lists import lists_app
+from ermes_cli.commands.journeys import journeys_app
+from ermes_cli.commands.subscriptions import subscriptions_app
+from ermes_cli.commands.providers import providers_app
+from ermes_cli.commands.tags import tags_app
+from ermes_cli.commands.ingest import ingest_app
+from ermes_cli.commands.data_paths import data_paths_app
+from ermes_cli.commands.keys import keys_app
+from ermes_cli.commands.export import export_app
+from ermes_cli.commands.auth_cmds import login as _login, logout as _logout
+from ermes_cli.commands.projects import projects_app, use as _use
+from ermes_cli.commands.write_cmds import write_app
+from ermes_cli.commands.metrics import metrics_app
+
+app.add_typer(campaigns_app, name="campaigns")
+app.add_typer(templates_app, name="templates")
+app.add_typer(users_app, name="users")
+app.add_typer(config_app, name="config")
+app.add_typer(lists_app, name="lists")
+app.add_typer(journeys_app, name="journeys")
+app.add_typer(subscriptions_app, name="subscriptions")
+app.add_typer(providers_app, name="providers")
+app.add_typer(tags_app, name="tags")
+app.add_typer(ingest_app, name="ingest")
+app.add_typer(data_paths_app, name="data-paths")
+app.add_typer(keys_app, name="keys")
+app.add_typer(export_app, name="export")
+app.add_typer(projects_app, name="projects")
+app.add_typer(write_app, name="write")
+app.add_typer(metrics_app, name="metrics")
+app.command(name="login", help="Auth0 device login + auto-discover projects")(_login)
+app.command(name="logout", help="Forget Auth0 tokens + cached projects")(_logout)
+app.command(name="use", help="Switch active project (by name or id)")(_use)

ermes_cli/manifest.py

@@ -0,0 +1,218 @@
+"""Route manifest loader for ermes-cli.
+
+Loads ``routes.yaml`` (next to this module) into a list of typed ``Route``
+records. The MCP server builds its tool list from the manifest, so adding
+a new read-only MCP tool is a YAML edit rather than a Python change.
+
+The hand-coded CLI in ``ermes_cli/commands/*.py`` is NOT generated from
+this file — the CLI surface is richer (CRUD + interactive prompts) and
+managed independently. If the manifest later grows to drive CLI commands,
+add a ``cli:`` block per route mirroring the publinker-cli pattern.
+
+Uses ``dataclasses`` + ``yaml`` to keep the runtime dependency surface
+small (every megabyte costs at ``pipx install`` time).
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Optional
+from urllib.parse import quote
+
+import yaml
+
+DEFAULT_ROUTES_FILE = Path(__file__).parent / "routes.yaml"
+
+# Allowed risk tiers. v0.3 only ships GET routes ("read"); mutating tiers
+# ("write", "delete") are reserved for v0.4+ when the confirmation UX lands.
+RISK_TIERS = {"read", "write", "delete", "admin"}
+
+# Allowed HTTP methods.
+METHODS = {"GET", "POST", "PUT", "PATCH", "DELETE"}
+
+# Allowed query-arg primitive types.
+QUERY_TYPES = {"str", "int", "bool"}
+
+# Matches `{name}` placeholders in API paths.
+_PATH_PLACEHOLDER = re.compile(r"\{([a-zA-Z_][a-zA-Z0-9_]*)\}")
+
+
+class ManifestError(ValueError):
+    """Raised when the manifest is malformed."""
+
+
+@dataclass(frozen=True)
+class MCPSpec:
+    expose: bool
+    tool_name: Optional[str]
+    description: str
+
+    @classmethod
+    def from_dict(cls, route_id: str, raw: dict) -> "MCPSpec":
+        if not isinstance(raw, dict):
+            raise ManifestError(f"{route_id}: mcp must be a dict")
+        expose = bool(raw.get("expose", False))
+        tool_name = raw.get("tool_name")
+        description = (raw.get("description") or "").strip()
+        if expose:
+            if not tool_name:
+                raise ManifestError(
+                    f"{route_id}: mcp.tool_name required when mcp.expose is true"
+                )
+            if not description:
+                raise ManifestError(
+                    f"{route_id}: mcp.description required when mcp.expose is true"
+                )
+        return cls(expose=expose, tool_name=tool_name, description=description)
+
+
+@dataclass(frozen=True)
+class PathArg:
+    """A positional argument required by the path (e.g., {campaign_id})."""
+
+    name: str
+    help: str
+
+    @classmethod
+    def from_path_placeholder(cls, name: str, helps: dict) -> "PathArg":
+        return cls(name=name, help=helps.get(name, f"The {name} value."))
+
+
+@dataclass(frozen=True)
+class QueryArg:
+    """An optional query-string argument (e.g., --limit)."""
+
+    name: str
+    help: str
+    type: str
+    default: Optional[object]
+    optional: bool
+
+    @classmethod
+    def from_dict(cls, route_id: str, raw: dict) -> "QueryArg":
+        if not isinstance(raw, dict) or "name" not in raw:
+            raise ManifestError(f"{route_id}: query_args entries need a 'name' key")
+        qtype = raw.get("type", "str")
+        if qtype not in QUERY_TYPES:
+            raise ManifestError(
+                f"{route_id}: query_arg {raw['name']!r} type must be one of "
+                f"{sorted(QUERY_TYPES)}, got {qtype!r}"
+            )
+        default = raw.get("default")
+        optional = bool(raw.get("optional", False))
+        # Optional + default-None is the common combination; default makes
+        # `optional` implicit only when no default is set.
+        if default is None and not optional:
+            optional = "default" not in raw
+        return cls(
+            name=raw["name"],
+            help=raw.get("help", ""),
+            type=qtype,
+            default=default,
+            optional=optional,
+        )
+
+
+@dataclass(frozen=True)
+class Route:
+    id: str
+    path: str
+    method: str
+    mcp: MCPSpec
+    risk: str
+    paginated: bool = False
+    path_args: tuple[PathArg, ...] = field(default_factory=tuple)
+    query_args: tuple[QueryArg, ...] = field(default_factory=tuple)
+
+    def render_path(self, values: dict[str, str]) -> str:
+        """Substitute ``{var}`` placeholders, URL-encoding each value as a
+        path segment. Missing keys raise ManifestError.
+        """
+        try:
+            encoded = {k: quote(str(v), safe="") for k, v in values.items()}
+            return self.path.format(**encoded)
+        except KeyError as exc:
+            raise ManifestError(
+                f"{self.id}: missing value for path arg {exc} when rendering {self.path}"
+            ) from exc
+
+    @classmethod
+    def from_dict(cls, raw: dict) -> "Route":
+        if not isinstance(raw, dict):
+            raise ManifestError(
+                f"route entry must be a dict, got {type(raw).__name__}"
+            )
+        try:
+            route_id = raw["id"]
+            path = raw["path"]
+            method = raw["method"].upper()
+        except KeyError as exc:
+            raise ManifestError(f"route missing required key {exc}") from exc
+        if method not in METHODS:
+            raise ManifestError(f"{route_id}: unknown HTTP method {method!r}")
+        risk = raw.get("risk", "read")
+        if risk not in RISK_TIERS:
+            raise ManifestError(
+                f"{route_id}: risk must be one of {sorted(RISK_TIERS)}, got {risk!r}"
+            )
+
+        path_arg_helps: dict[str, str] = {}
+        for entry in raw.get("args", []) or []:
+            if not isinstance(entry, dict) or "name" not in entry:
+                raise ManifestError(f"{route_id}: args entries need a 'name' key")
+            path_arg_helps[entry["name"]] = entry.get("help", "")
+
+        placeholders = _PATH_PLACEHOLDER.findall(path)
+        path_args = tuple(
+            PathArg.from_path_placeholder(name, path_arg_helps)
+            for name in placeholders
+        )
+
+        query_args = tuple(
+            QueryArg.from_dict(route_id, q)
+            for q in (raw.get("query_args") or [])
+        )
+
+        return cls(
+            id=route_id,
+            path=path,
+            method=method,
+            mcp=MCPSpec.from_dict(route_id, raw["mcp"]),
+            risk=risk,
+            paginated=bool(raw.get("paginated", False)),
+            path_args=path_args,
+            query_args=query_args,
+        )
+
+
+def load_manifest(path: Path = DEFAULT_ROUTES_FILE) -> list[Route]:
+    """Load + validate the manifest. Raises ManifestError on any structural issue."""
+    raw = yaml.safe_load(path.read_text())
+    if not isinstance(raw, list):
+        raise ManifestError(
+            f"{path}: top-level must be a YAML list, got {type(raw).__name__}"
+        )
+
+    routes = [Route.from_dict(entry) for entry in raw]
+
+    ids: set[str] = set()
+    mcp_tool_names: set[str] = set()
+    for route in routes:
+        if route.id in ids:
+            raise ManifestError(f"duplicate route id: {route.id}")
+        ids.add(route.id)
+        if route.mcp.expose and route.mcp.tool_name in mcp_tool_names:
+            raise ManifestError(
+                f"{route.id}: duplicate MCP tool name {route.mcp.tool_name!r}"
+            )
+        if route.mcp.expose and route.mcp.tool_name:
+            mcp_tool_names.add(route.mcp.tool_name)
+
+    return routes
+
+
+def exposed_routes(routes: list[Route]) -> list[Route]:
+    """Return the subset of routes where ``mcp.expose`` is true."""
+    return [r for r in routes if r.mcp.expose]