pushmetrics-cli 0.1.0__py3-none-any.whl

pm/__init__.py

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

pm/__main__.py

@@ -0,0 +1,4 @@
+from pm.cli import cli
+
+if __name__ == "__main__":
+    cli()

pm/_alias.py

@@ -0,0 +1,164 @@
+"""Click group with command-name aliases + fuzzy "Did you mean?".
+
+pm-tool introduces canonical verbs (`list`, `create`, `delete`, `get`) that
+replace older non-REST names (`ls`, `add`, `remove`). The legacy names stay
+as soft aliases — both forms work — so existing CLI users aren't broken.
+Same pattern for the plural→singular group rename (`reports`→`report`).
+
+When neither a direct match nor an alias resolves, the group attempts a
+fuzzy suggestion via difflib so typos like ``pm blcok`` get a hint
+toward ``block`` instead of a bare "No such command" error.
+
+Usage:
+
+    from pm._alias import AliasedGroup
+
+    @click.group(name="user", cls=AliasedGroup, aliases={"add": "create"})
+    def user():
+        ...
+
+    @user.command(name="create")
+    def create_user(...):
+        ...
+
+Now ``pm user create`` and ``pm user add`` both resolve to ``create_user``.
+Aliases are NOT listed in ``--help`` (to keep the canonical surface clean);
+``pm help`` (pm-foundation) is the agent-facing help system and will
+mention compatibility aliases explicitly when relevant.
+
+Groups that don't need legacy aliases still benefit from the fuzzy
+suggestion behavior — pass ``aliases={}`` (the default) and the
+suggestion path is the only added behavior over a plain ``click.Group``.
+"""
+from __future__ import annotations
+
+import difflib
+from typing import Optional
+
+import click
+
+
+# Fuzzy threshold. Codex review round 2 (2026-06-09) showed that 0.7
+# is too tight for 3-char verbs — common transpositions/substitutions
+# like ``gte→get`` and ``rnu→run`` score about 0.67. 0.6 picks those
+# up while still rejecting genuinely-different tokens (``xyz`` vs
+# any verb scores ~0.0). The MIN_LEN floor was also dropped: short
+# tokens like ``ge → get`` (0.8) are HELPFUL suggestions, not noise.
+_FUZZY_CUTOFF = 0.6
+
+
+class AliasedGroup(click.Group):
+    """Click group that resolves a configurable map of legacy command
+    names to their canonical equivalents.
+
+    Aliases are checked AFTER direct command lookup, so a real command
+    with the same name as an alias would always win (defensive — no
+    silent shadowing). Unknown commands trigger a fuzzy suggestion
+    when one is available; otherwise Click's standard error renders.
+
+    Subgroups created via ``@aliased_group_instance.group()`` inherit
+    this class via the ``group()`` override below — without it, nested
+    ``@cli.group()`` declarations default back to ``click.Group`` and
+    miss the typo behavior. Codex review round 2 catch on
+    ``cli/pm/cli.py:85`` (``@cli.group(name="config")``).
+    """
+
+    def __init__(self, *args, aliases: Optional[dict[str, str]] = None, **kwargs):
+        super().__init__(*args, **kwargs)
+        self._aliases: dict[str, str] = aliases or {}
+
+    def group(self, *args, **kwargs):
+        """Default subgroup class to ``type(self)`` so nested
+        ``@aliased_group.group()`` declarations inherit the runtime
+        class — transitively, for subclasses of ``AliasedGroup``. Codex
+        round 3 catch: hard-coding ``AliasedGroup`` here lost subclass
+        behavior on subgroups (a hypothetical ``FancyAliasedGroup``
+        would have nested groups fall back to plain ``AliasedGroup``).
+        Callers can still override with ``cls=`` if they need a
+        different group class for a specific subgroup.
+        """
+        kwargs.setdefault("cls", type(self))
+        return super().group(*args, **kwargs)
+
+    def get_command(self, ctx: click.Context, cmd_name: str):
+        rv = super().get_command(ctx, cmd_name)
+        if rv is not None:
+            return rv
+        canonical = self._aliases.get(cmd_name)
+        if canonical is not None:
+            return super().get_command(ctx, canonical)
+        return None
+
+    def resolve_command(self, ctx: click.Context, args):
+        """Run Click's normal resolution; on a missing-command
+        ``UsageError``, attempt a fuzzy suggestion.
+
+        Codex round 2 catch: catching every ``UsageError`` over-fires
+        on option errors like ``pm --block`` ("No such option"), which
+        would mis-render as "Did you mean 'block'?". Filter by the
+        ``No such command`` prefix Click uses for unknown-command
+        errors so option errors fall through to the standard renderer.
+        """
+        try:
+            return super().resolve_command(ctx, args)
+        except click.UsageError as exc:
+            if not _is_no_such_command_error(exc):
+                raise
+            attempted = args[0] if args else ""
+            suggestion = self._fuzzy_suggest(ctx, attempted)
+            if suggestion is None:
+                raise
+            raise click.UsageError(
+                f"No such command {attempted!r}. "
+                f"Did you mean {suggestion!r}?",
+                ctx=ctx,
+            ) from exc
+
+    def _fuzzy_suggest(self, ctx: click.Context, attempted: str) -> Optional[str]:
+        """Return the best fuzzy match for ``attempted`` against this
+        group's registered commands, or None when no candidate scores
+        above the cutoff.
+
+        Codex round 2 catch: aliases are included in the candidate
+        SEARCH set so typos near a legacy alias still resolve, but
+        the returned suggestion is the canonical command — never the
+        alias. This matches the project's "aliases work but aren't
+        advertised in --help" stance.
+
+        Codex round 3 catch: defensive check that the resolved
+        canonical actually exists in ``list_commands``. A malformed
+        alias map (``aliases={"ls": "nonexistent"}``) would otherwise
+        surface ``"nonexistent"`` as the suggestion — a bad UX on
+        top of a config error.
+        """
+        if not attempted:
+            return None
+        registered = set(self.list_commands(ctx))
+        candidates = list(registered) + list(self._aliases.keys())
+        matches = difflib.get_close_matches(
+            attempted, candidates, n=1, cutoff=_FUZZY_CUTOFF,
+        )
+        if not matches:
+            return None
+        match = matches[0]
+        # Resolve alias → canonical. If ``match`` is a real command,
+        # ``self._aliases.get(match)`` returns None and we keep the
+        # original — the get() default lookup pattern.
+        resolved = self._aliases.get(match, match)
+        # Defensive: drop dangling-alias suggestions rather than
+        # render a misleading "Did you mean ..." for a command that
+        # doesn't exist.
+        if resolved not in registered:
+            return None
+        return resolved
+
+
+def _is_no_such_command_error(exc: click.UsageError) -> bool:
+    """Click renders unknown-command errors with a message starting
+    ``"No such command"``. Option errors start ``"No such option"`` and
+    other UsageErrors (missing args, invalid values) have unrelated
+    prefixes. Filter strictly so the fuzzy suggestion only attaches
+    where it makes sense.
+    """
+    message = exc.message if exc.message else ""
+    return message.lower().startswith("no such command")

pm/auth/device_flow.py

@@ -0,0 +1,187 @@
+"""Auth0 Device Authorization Flow (RFC 8628)."""
+from __future__ import annotations
+
+import logging
+import time
+import webbrowser
+from dataclasses import dataclass
+from typing import Optional
+
+import requests
+
+from pm.log import log_request, log_response, redact_secrets
+
+logger = logging.getLogger(__name__)
+
+
+class DeviceFlowError(RuntimeError):
+    pass
+
+
+# auth0_domain is optional on a profile (token login never needs it), so the
+# device flow is where its absence is caught: before any URL is built from it.
+MISSING_DOMAIN_MESSAGE = (
+    "Browser login needs auth0_domain on this profile. Set it with "
+    "`pm config set <profile> auth0_domain auth.pushmetrics.io`, or use "
+    "`pm login --token` instead."
+)
+
+
+def _require_domain(domain: Optional[str]) -> str:
+    if not domain:
+        raise DeviceFlowError(MISSING_DOMAIN_MESSAGE)
+    return domain
+
+
+@dataclass
+class DeviceCodePayload:
+    device_code: str
+    user_code: str
+    verification_uri: str
+    verification_uri_complete: str
+    expires_in: int
+    interval: int
+
+
+@dataclass
+class TokenPayload:
+    access_token: str
+    refresh_token: Optional[str]
+    id_token: Optional[str]
+    expires_in: int
+    token_type: str
+    scope: Optional[str]
+
+
+def request_device_code(
+    domain: Optional[str],
+    client_id: str,
+    audience: Optional[str],
+    scope: str = "openid profile email offline_access",
+) -> DeviceCodePayload:
+    url = f"https://{_require_domain(domain)}/oauth/device/code"
+    started = log_request(logger, "POST", url)
+    response = requests.post(
+        url,
+        data={
+            "client_id": client_id,
+            "scope": scope,
+            "audience": audience,
+        },
+        timeout=30,
+    )
+    log_response(logger, response, started)
+    if response.status_code != 200:
+        raise DeviceFlowError(
+            f"Auth0 device code request failed: {response.status_code} {redact_secrets(response.text[:300])}"
+        )
+    body = response.json()
+    return DeviceCodePayload(
+        device_code=body["device_code"],
+        user_code=body["user_code"],
+        verification_uri=body["verification_uri"],
+        verification_uri_complete=body.get(
+            "verification_uri_complete", body["verification_uri"]
+        ),
+        expires_in=body.get("expires_in", 900),
+        interval=body.get("interval", 5),
+    )
+
+
+def poll_for_token(
+    domain: Optional[str],
+    client_id: str,
+    payload: DeviceCodePayload,
+    *,
+    no_browser: bool = False,
+) -> TokenPayload:
+    """Poll Auth0 until the user approves the device code or it expires."""
+    domain = _require_domain(domain)
+    if not no_browser:
+        try:
+            webbrowser.open(payload.verification_uri_complete)
+        except Exception:
+            pass
+
+    deadline = time.monotonic() + payload.expires_in
+    interval = max(1, payload.interval)
+
+    while True:
+        if time.monotonic() >= deadline:
+            raise DeviceFlowError("Device code expired before authorization completed.")
+
+        time.sleep(interval)
+
+        url = f"https://{domain}/oauth/token"
+        started = log_request(logger, "POST", url)
+        response = requests.post(
+            url,
+            data={
+                "grant_type": "urn:ietf:params:oauth:grant-type:device_code",
+                "device_code": payload.device_code,
+                "client_id": client_id,
+            },
+            timeout=30,
+        )
+        log_response(logger, response, started)
+
+        if response.status_code == 200:
+            body = response.json()
+            return TokenPayload(
+                access_token=body["access_token"],
+                refresh_token=body.get("refresh_token"),
+                id_token=body.get("id_token"),
+                expires_in=body.get("expires_in", 0),
+                token_type=body.get("token_type", "Bearer"),
+                scope=body.get("scope"),
+            )
+
+        try:
+            err = response.json()
+            err_code = err.get("error", "")
+        except Exception:
+            err_code = ""
+
+        if err_code == "authorization_pending":
+            continue
+        if err_code == "slow_down":
+            interval = min(interval + 5, 60)
+            continue
+        if err_code == "expired_token":
+            raise DeviceFlowError("Authorization timed out — the user code expired.")
+        if err_code == "access_denied":
+            raise DeviceFlowError("Authorization was denied by the user.")
+        raise DeviceFlowError(
+            f"Auth0 token poll failed: {response.status_code} {redact_secrets(response.text[:300])}"
+        )
+
+
+def refresh_auth0_token(
+    domain: Optional[str], client_id: str, refresh_token: str
+) -> TokenPayload:
+    """Exchange a refresh token for a fresh access token."""
+    url = f"https://{_require_domain(domain)}/oauth/token"
+    started = log_request(logger, "POST", url)
+    response = requests.post(
+        url,
+        data={
+            "grant_type": "refresh_token",
+            "client_id": client_id,
+            "refresh_token": refresh_token,
+        },
+        timeout=30,
+    )
+    log_response(logger, response, started)
+    if response.status_code != 200:
+        raise DeviceFlowError(
+            f"Auth0 refresh failed: {response.status_code} {redact_secrets(response.text[:300])}"
+        )
+    body = response.json()
+    return TokenPayload(
+        access_token=body["access_token"],
+        refresh_token=body.get("refresh_token", refresh_token),
+        id_token=body.get("id_token"),
+        expires_in=body.get("expires_in", 0),
+        token_type=body.get("token_type", "Bearer"),
+        scope=body.get("scope"),
+    )

pm/auth/exchange.py

@@ -0,0 +1,79 @@
+"""Exchange an Auth0 access token for a PushMetrics session.
+
+This hits POST /api/v1/security/login with an `Authorization: Bearer <auth0_token>`
+header. The response sets the Flask session cookie (carrying workspace_id for
+Postgres RLS) onto the provided requests.Session, AND returns PushMetrics-issued
+JWT access/refresh tokens in the body.
+
+This is the Auth0 device-flow (cookie) login path, one of the CLI's three
+auth modes. The session cookie is what authenticates subsequent calls in
+this mode; the returned JWTs are stored for silent re-login. Programmatic
+callers use ``PM_API_TOKEN`` (PAT) or ``PM_API_JWT`` (delegation) instead and
+never hit this path - see ``session.py`` for the resolution order.
+"""
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from typing import Optional
+
+import requests
+
+from pm.log import log_request, log_response, redact_secrets
+
+logger = logging.getLogger(__name__)
+
+
+class LoginError(RuntimeError):
+    pass
+
+
+@dataclass
+class PMLoginResult:
+    pm_access_token: Optional[str]
+    pm_refresh_token: Optional[str]
+
+
+def exchange_for_session(
+    session: requests.Session,
+    api_url: str,
+    auth0_access_token: str,
+    *,
+    want_refresh: bool = True,
+) -> PMLoginResult:
+    url = f"{api_url}/api/v1/security/login"
+    started = log_request(logger, "POST", url)
+    resp = session.post(
+        url,
+        json={"refresh": want_refresh},
+        headers={"Authorization": f"Bearer {auth0_access_token}"},
+        timeout=30,
+    )
+    log_response(logger, resp, started)
+    if resp.status_code != 200:
+        raise LoginError(
+            f"PushMetrics login failed: {resp.status_code} {redact_secrets(resp.text[:300])}"
+        )
+
+    try:
+        body = resp.json() if resp.content else {}
+    except ValueError:
+        raise LoginError(
+            "PushMetrics login returned a non-JSON response (got HTML/redirect). "
+            "This usually means the backend rejected the Auth0 token "
+            "(verify_auth0_token failed) and fell back to the standard login page. "
+            f"First 300 chars: {redact_secrets(resp.text[:300])!r}"
+        )
+
+    pm_access_token = body.get("access_token")
+    if not pm_access_token:
+        raise LoginError(
+            "PushMetrics login succeeded (200) but returned no access_token. "
+            "The Auth0 token was not accepted by /security/login. "
+            f"Body: {redact_secrets(repr(body))}"
+        )
+
+    return PMLoginResult(
+        pm_access_token=pm_access_token,
+        pm_refresh_token=body.get("refresh_token"),
+    )

pm/auth/jwt_cache.py

@@ -0,0 +1,163 @@
+"""Per-profile cache of the JWT exchanged from a Personal Access Token.
+
+``PMSession`` exchanges the PAT once per process. Every ``pm`` invocation is
+a process, and the exchange endpoint is rate-limited per IP (10/min in
+prod), so a shell loop over ``pm`` commands hit 429 on the 11th call. This
+module keeps the short-lived JWT across processes with the same safety as
+the PAT itself: OS keyring first, else a ``0600`` fallback file.
+
+A record is only a hit when ALL of these hold; anything else is a miss:
+
+- the profile name matches (the record key);
+- ``api_url`` matches, so a JWT minted for prod never rides along to a host
+  given with ``--api-url`` / ``PM_API_URL`` under the same profile;
+- the PAT fingerprint matches, so a changed ``PM_API_TOKEN`` or a fresh
+  ``pm login --token`` never reuses the previous token's JWT;
+- the wall-clock expiry (exchange time + ``expires_in`` - margin) is in the
+  future. The TTL is the server's; it is never extended client-side.
+
+The raw PAT is never stored here, only ``sha256(pat)[:16]``. The JWT value
+is never logged: hit/miss lines carry the profile name only. Delegation
+mode (``PM_API_JWT``) never reads or writes this cache.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import logging
+import re
+import time
+from dataclasses import asdict, dataclass
+from typing import Optional
+
+from pm.auth.secret_files import read_private_json, write_private_json
+from pm.config import CONFIG_DIR, keyring_account
+from pm.log import timed
+
+try:
+    import keyring
+    _KEYRING_AVAILABLE = True
+except Exception:
+    _KEYRING_AVAILABLE = False
+
+logger = logging.getLogger(__name__)
+
+# Distinct from the PAT ("pushmetrics-cli-pat") and cookie ("pushmetrics-cli")
+# services so the cached JWT can never overwrite or shadow either.
+KEYRING_SERVICE = "pushmetrics-cli-jwt"
+FALLBACK_FILE = CONFIG_DIR / "jwt_cache.json"
+
+# A JWT is base64url segments joined by dots; anything with whitespace or
+# control characters must never reach a header. Shared with PM_API_JWT.
+JWT_SHAPE_RE = re.compile(r"^[A-Za-z0-9._\-]+$")
+
+# Seconds taken off the server TTL so a JWT is never presented in the last
+# moments before the server stops accepting it.
+EXPIRY_MARGIN_SECONDS = 60
+
+
+@dataclass
+class CachedJwt:
+    jwt: str
+    expires_at: float
+    api_url: str
+    pat_fingerprint: str
+
+    def seconds_left(self, now: Optional[float] = None) -> float:
+        return self.expires_at - (time.time() if now is None else now)
+
+
+def fingerprint(raw_pat: str) -> str:
+    """Non-reversible identity of a PAT; the raw value is never persisted."""
+    return hashlib.sha256(raw_pat.encode("utf-8")).hexdigest()[:16]
+
+
+def load(profile: str, api_url: str, raw_pat: str) -> Optional[CachedJwt]:
+    """Return the cached JWT bound to this profile, host and PAT, if still valid."""
+    record = _read_record(profile)
+    if record is None:
+        logger.debug("jwt cache miss for profile %s", profile)
+        return None
+    if record.api_url != api_url or record.pat_fingerprint != fingerprint(raw_pat):
+        logger.debug("jwt cache miss for profile %s (different host or token)", profile)
+        return None
+    if record.seconds_left() <= 0:
+        logger.debug("jwt cache miss for profile %s (expired)", profile)
+        return None
+    logger.debug("jwt cache hit for profile %s", profile)
+    return record
+
+
+def save(profile: str, api_url: str, raw_pat: str, jwt: str, expires_in: int) -> None:
+    record = CachedJwt(
+        jwt=jwt,
+        expires_at=time.time() + max(0, expires_in - EXPIRY_MARGIN_SECONDS),
+        api_url=api_url,
+        pat_fingerprint=fingerprint(raw_pat),
+    )
+    _write_record(profile, record)
+
+
+def clear(profile: str) -> None:
+    """Forget the cached JWT for ``profile`` (keyring and file). Idempotent."""
+    if _KEYRING_AVAILABLE:
+        try:
+            keyring.delete_password(KEYRING_SERVICE, keyring_account(profile))
+        except Exception as exc:
+            logger.debug("keyring jwt delete for %s: %s", profile, type(exc).__name__)
+    data = read_private_json(FALLBACK_FILE)
+    if profile in data:
+        del data[profile]
+        write_private_json(FALLBACK_FILE, data)
+
+
+# ── storage ─────────────────────────────────────────────────────────
+
+
+def _read_record(profile: str) -> Optional[CachedJwt]:
+    raw = None
+    if _KEYRING_AVAILABLE:
+        try:
+            with timed(logger, "keyring.load_jwt"):
+                raw = keyring.get_password(KEYRING_SERVICE, keyring_account(profile))
+        except Exception as exc:
+            logger.debug("keyring jwt load failed for %s: %s", profile, type(exc).__name__)
+    if raw:
+        return _parse(raw, profile)
+    data = read_private_json(FALLBACK_FILE).get(profile)
+    return _parse(data, profile) if data else None
+
+
+def _parse(raw, profile: str) -> Optional[CachedJwt]:
+    """A corrupt record is a miss, never a traceback."""
+    try:
+        data = json.loads(raw) if isinstance(raw, str) else raw
+        record = CachedJwt(
+            jwt=str(data["jwt"]),
+            expires_at=float(data["expires_at"]),
+            api_url=str(data["api_url"]),
+            pat_fingerprint=str(data["pat_fingerprint"]),
+        )
+    except (KeyError, TypeError, ValueError):
+        logger.debug("jwt cache record for %s is corrupt; treating as miss", profile)
+        return None
+    if not JWT_SHAPE_RE.fullmatch(record.jwt):
+        # A hand-edited record would otherwise surface as a transport error
+        # ("Could not reach ... (InvalidHeader)") and misdirect the user.
+        logger.debug("jwt cache record for %s is malformed; treating as miss", profile)
+        return None
+    return record
+
+
+def _write_record(profile: str, record: CachedJwt) -> None:
+    storable = asdict(record)
+    if _KEYRING_AVAILABLE:
+        try:
+            with timed(logger, "keyring.save_jwt"):
+                keyring.set_password(KEYRING_SERVICE, keyring_account(profile), json.dumps(storable))
+            return
+        except Exception as exc:
+            logger.debug("keyring jwt save failed for %s: %s", profile, type(exc).__name__)
+    data = read_private_json(FALLBACK_FILE)
+    data[profile] = storable
+    write_private_json(FALLBACK_FILE, data)

pm/auth/secret_files.py

@@ -0,0 +1,58 @@
+"""Private JSON files for the credential fallback stores.
+
+One implementation of the "0600 from creation" rule for every file that can
+hold a secret (``credentials.json``, ``tokens.json``, ``jwt_cache.json``):
+
+- the data is written to a sibling temp file opened ``O_CREAT`` with mode
+  ``0o600``, so there is no window in which a world-readable file holds the
+  secret (write-then-chmod has one, and a crash between the two steps leaves
+  it open for good);
+- the temp file is then ``os.replace``d over the target, so a crash mid-write
+  leaves the previous record intact rather than a torn file;
+- a corrupt or missing file reads as empty, never as a traceback.
+"""
+from __future__ import annotations
+
+import json
+import logging
+import os
+import secrets
+from pathlib import Path
+from typing import Any, Dict
+
+logger = logging.getLogger(__name__)
+
+PRIVATE_MODE = 0o600
+
+
+def read_private_json(path: Path) -> Dict[str, Any]:
+    """Return the file's JSON object, or ``{}`` when it is missing or unreadable."""
+    if not path.exists():
+        return {}
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, ValueError) as exc:
+        logger.debug("ignoring unreadable %s: %s", path.name, type(exc).__name__)
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def write_private_json(path: Path, data: Dict[str, Any]) -> None:
+    """Atomically replace ``path`` with ``data``, owner-readable only."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    # Unique name + O_EXCL: a leftover temp file from a crashed process is
+    # never reopened with whatever mode it had.
+    tmp = path.with_name(f".{path.name}.{secrets.token_hex(8)}.tmp")
+    fd = os.open(tmp, os.O_WRONLY | os.O_CREAT | os.O_EXCL, PRIVATE_MODE)
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as f:
+            f.write(json.dumps(data))
+        os.replace(tmp, path)
+    except BaseException:
+        # Best-effort rollback: an unlink failure must never replace the
+        # original write/replace error the caller needs to see.
+        try:
+            os.unlink(tmp)
+        except OSError as unlink_exc:
+            logger.debug("could not remove %s: %s", tmp.name, type(unlink_exc).__name__)
+        raise