tripwire-cli 0.2.0__py3-none-any.whl

tripwire_cli/__main__.py

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

tripwire_cli/cli.py

@@ -0,0 +1,365 @@
+"""Command-line client for Tripwire canaries.
+
+Commands:
+  tripwire login                       log in (email-code by default), cache a
+                                       token; --user-id/--password for operators
+  tripwire logout                      forget the cached token
+  tripwire whoami                      print the cached identity
+  tripwire canaries list               list your canaries (summary only)
+  tripwire canaries get <id>           show one canary summary
+  tripwire canaries create --type ...  create a canary; its credential is
+                                       returned once, in this response
+  tripwire canaries deactivate <id>    deactivate a canary
+  tripwire canaries delete <id>        delete a canary
+
+`login` does not take a server flag. The server is resolved as
+$TRIPWIRE_SERVER, then the last-used cached server, then the default; set
+$TRIPWIRE_SERVER to point at a self-hosted or test server.
+"""
+
+from __future__ import annotations
+
+import functools
+import json
+import os
+import subprocess
+from collections.abc import Callable
+from typing import Any
+
+import click
+
+from tripwire_cli import credentials
+from tripwire_cli.client import CREATE_READ_TIMEOUT, ApiClient, ApiError
+
+
+def _git_user_email() -> str | None:
+    """Best-effort default email from ``git config user.email``; ``None`` if
+    git is absent or unset. Shown to the user as a default, never used
+    silently."""
+    try:
+        result = subprocess.run(
+            ["git", "config", "user.email"],
+            capture_output=True,
+            text=True,
+            timeout=5,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return None
+    email = result.stdout.strip()
+    return email or None
+
+DEFAULT_SERVER = "https://tripwire.so/api/v1"
+
+CANARY_TYPES = ["dns_label", "aws_access_key", "anthropic_api_key", "github_pat"]
+
+# How long the create read timeout may run, in seconds. Must stay above the
+# server's synchronous create wait window (180s) so the client never abandons a
+# request whose one-time credential reveal the server is still preparing.
+CREATE_TIMEOUT_ENV = "TRIPWIRE_CREATE_TIMEOUT"
+
+# How many times to re-prompt for the emailed code before giving up. Re-prompts
+# never re-call /auth/login/start (which is rate-limited); they re-submit a new
+# code against the same challenge.
+EMAIL_CODE_ATTEMPTS = 3
+
+
+def resolve_login_server(env: dict[str, str], cached: str | None) -> str:
+    """Server URL for `login`: env override, else the last-used cached server,
+    else the default."""
+    return env.get("TRIPWIRE_SERVER") or cached or DEFAULT_SERVER
+
+
+def build_create_payload(*, canary_type: str, memo: str | None = None) -> dict[str, Any]:
+    """Build the create request body from the supported flags."""
+    payload: dict[str, Any] = {"type": canary_type}
+    if memo:
+        payload["memo"] = memo
+    return payload
+
+
+class Context:
+    """Shared state for the commands: the credential store and a factory that
+    builds an :class:`ApiClient` from a server URL and optional token. Both are
+    injectable so tests can supply fakes."""
+
+    def __init__(
+        self,
+        store: credentials.CredentialStore | None = None,
+        client_factory: Callable[[str, str | None], ApiClient] | None = None,
+        git_email: Callable[[], str | None] | None = None,
+    ):
+        self.store = store or credentials.default_store()
+        self._client_factory = client_factory or (
+            lambda server, token=None: ApiClient(base_url=server, token=token)
+        )
+        # Injectable so tests can supply a fake; defaults to `git config
+        # user.email`.
+        self._git_email = git_email or _git_user_email
+
+    def git_email(self) -> str | None:
+        return self._git_email()
+
+    def client(self, server: str, token: str | None = None) -> ApiClient:
+        return self._client_factory(server, token)
+
+    def authed_client(self) -> ApiClient:
+        creds = self.store.load()
+        return self.client(creds.server, creds.access_token)
+
+    def cached_server(self) -> str | None:
+        try:
+            return self.store.load().server
+        except credentials.NoCredentialsError:
+            return None
+
+
+def _handle_errors(func):
+    """Translate API/credential errors into a clean CLI error and exit code."""
+
+    @functools.wraps(func)
+    def wrapper(*args, **kwargs):
+        try:
+            return func(*args, **kwargs)
+        except ApiError as exc:
+            message = f"{exc.status}: {exc.detail}"
+            if exc.status == 401:
+                message += "\nhint: run `tripwire login`"
+            raise click.ClickException(message) from exc
+        except (credentials.NoCredentialsError, ValueError) as exc:
+            raise click.ClickException(str(exc)) from exc
+
+    return wrapper
+
+
+def _echo_json(value: Any) -> None:
+    click.echo(json.dumps(value, indent=2))
+
+
+@click.group()
+@click.version_option(package_name="tripwire-cli", prog_name="tripwire")
+@click.pass_context
+def cli(ctx: click.Context) -> None:
+    """Tripwire canary client."""
+    ctx.obj = ctx.obj or Context()
+
+
+@cli.command()
+@click.option("--user-id", help="operator user id (selects password login)")
+@click.option(
+    "--password", help="operator password (selects password login; prefer the prompt)"
+)
+@click.pass_obj
+@_handle_errors
+def login(obj: Context, user_id: str | None, password: str | None) -> None:
+    """Log in and cache a token.
+
+    Defaults to passwordless email-code login. Passing --user-id or --password
+    selects the operator (user-id + password) login instead, so operator
+    scripts keep working unchanged.
+    """
+    server = resolve_login_server(dict(os.environ), obj.cached_server())
+    client = obj.client(server)
+    if user_id is not None or password is not None:
+        creds = _password_login(client, server, user_id, password)
+    else:
+        creds = _email_login(client, server, obj.git_email())
+    path = obj.store.save(creds)
+    click.echo(f"logged in as {creds.user_id} ({creds.role}); token cached at {path}")
+
+
+def _password_login(
+    client: ApiClient, server: str, user_id: str | None, password: str | None
+) -> credentials.Credentials:
+    """Operator login: user-id + password."""
+    user_id = user_id or click.prompt("user_id")
+    password = password or click.prompt("password", hide_input=True)
+    response = client.login(user_id, password)
+    return _credentials_from_login(server, response)
+
+
+def _email_login(
+    client: ApiClient, server: str, default_email: str | None
+) -> credentials.Credentials:
+    """Passwordless email-code login. Calls /auth/login/start once (it is
+    rate-limited), then re-prompts for the 6-digit code in-band on an
+    invalid/expired code without re-calling start."""
+    email = click.prompt("email", default=default_email)
+    client.login_start(email)
+    click.echo(f"sent a 6-digit sign-in code to {email}; check your inbox.")
+    last_error: ApiError | None = None
+    for attempt in range(EMAIL_CODE_ATTEMPTS):
+        code = click.prompt("code")
+        try:
+            response = client.login_with_code(email, code)
+        except ApiError as exc:
+            if exc.status == 400 and exc.detail == "invalid_or_expired_code":
+                last_error = exc
+                remaining = EMAIL_CODE_ATTEMPTS - attempt - 1
+                if remaining:
+                    click.echo(
+                        f"invalid or expired code; {remaining} attempt(s) left.",
+                        err=True,
+                    )
+                continue
+            raise
+        return _credentials_from_login(server, response, email=email)
+    # Exhausted the re-prompt budget; surface the last invalid-code error.
+    raise last_error if last_error is not None else ApiError(400, "invalid_or_expired_code")
+
+
+def _credentials_from_login(
+    server: str, response: dict[str, Any], email: str | None = None
+) -> credentials.Credentials:
+    return credentials.Credentials(
+        server=server,
+        user_id=response["user_id"],
+        access_token=response["access_token"],
+        expires_at=int(response["expires_at"]),
+        role=response["role"],
+        email=email,
+    )
+
+
+@cli.command()
+@click.pass_obj
+@_handle_errors
+def logout(obj: Context) -> None:
+    """Forget the cached token."""
+    click.echo("cached token removed" if obj.store.clear() else "no cached token")
+
+
+@cli.command()
+@click.pass_obj
+@_handle_errors
+def whoami(obj: Context) -> None:
+    """Print the cached identity."""
+    creds = obj.store.load()
+    click.echo(f"server:   {creds.server}")
+    click.echo(f"user_id:  {creds.user_id}")
+    if creds.email:
+        click.echo(f"email:    {creds.email}")
+    click.echo(f"role:     {creds.role}")
+
+
+@cli.group()
+def canaries() -> None:
+    """Manage canaries."""
+
+
+@canaries.command("list")
+@click.pass_obj
+@_handle_errors
+def canaries_list(obj: Context) -> None:
+    """List the canaries you own (summary only)."""
+    _echo_json(obj.authed_client().list_canaries())
+
+
+@canaries.command("get")
+@click.argument("canary_id")
+@click.pass_obj
+@_handle_errors
+def canaries_get(obj: Context, canary_id: str) -> None:
+    """Show one canary summary (no credential)."""
+    _echo_json(obj.authed_client().get_canary(canary_id))
+
+
+@canaries.command("create")
+@click.option(
+    "--type", "canary_type", type=click.Choice(CANARY_TYPES), required=True
+)
+@click.option("--memo", help="free-form note about this canary")
+@click.option(
+    "--timeout",
+    "timeout",
+    type=float,
+    default=None,
+    help=(
+        "read timeout in seconds for this create "
+        f"(env {CREATE_TIMEOUT_ENV}; default 240). Must exceed the server's "
+        "~180s provisioning wait."
+    ),
+)
+@click.pass_obj
+@_handle_errors
+def canaries_create(
+    obj: Context, canary_type: str, memo: str | None, timeout: float | None
+) -> None:
+    """Create a canary. The credential is returned once, in this response."""
+    read_timeout = _resolve_create_timeout(timeout, dict(os.environ))
+    payload = build_create_payload(canary_type=canary_type, memo=memo)
+    click.echo(
+        "creating the canary (usually a second or two; up to ~2 min if the "
+        "warm pool is cold).",
+        err=True,
+    )
+    try:
+        result = obj.authed_client().create_canary(payload, timeout=read_timeout)
+    except ApiError as exc:
+        message = _create_error_message(exc)
+        if message is None:
+            raise
+        raise click.ClickException(message) from exc
+    _echo_json(result)
+
+
+def _resolve_create_timeout(flag: float | None, env: dict[str, str]) -> float:
+    """Read timeout for create, in seconds: --timeout flag, else
+    ``TRIPWIRE_CREATE_TIMEOUT`` env, else ``CREATE_READ_TIMEOUT`` (240). Always
+    above the server's ~180s provisioning wait so the client never abandons a
+    create whose one-time reveal is still being prepared."""
+    if flag is not None:
+        return flag
+    raw = env.get(CREATE_TIMEOUT_ENV)
+    if not raw:
+        return CREATE_READ_TIMEOUT
+    try:
+        return float(raw)
+    except ValueError as exc:
+        raise click.ClickException(
+            f"invalid {CREATE_TIMEOUT_ENV}={raw!r}: must be a number of seconds"
+        ) from exc
+
+
+def _create_error_message(exc: ApiError) -> str | None:
+    """Friendly text for the create-specific failures, or ``None`` to fall back
+    to the generic error handler."""
+    if exc.status == 429 and exc.detail == "canary_pending":
+        return (
+            "canary is still provisioning, so its one-time credential reveal was "
+            "not returned in this response and cannot be recovered. creating "
+            "again would mint a second canary and trip the per-type quota; "
+            "instead, find this orphan with `tripwire canaries list`, delete it "
+            "with `tripwire canaries delete <id>`, then recreate."
+        )
+    if exc.status == 502 and exc.detail == "provisioning_failed":
+        return (
+            "canary provisioning failed; nothing was issued. "
+            "try again, and if it persists contact support."
+        )
+    return None
+
+
+@canaries.command("deactivate")
+@click.argument("canary_id")
+@click.pass_obj
+@_handle_errors
+def canaries_deactivate(obj: Context, canary_id: str) -> None:
+    """Deactivate a canary."""
+    _echo_json(obj.authed_client().deactivate_canary(canary_id))
+
+
+@canaries.command("delete")
+@click.argument("canary_id")
+@click.pass_obj
+@_handle_errors
+def canaries_delete(obj: Context, canary_id: str) -> None:
+    """Delete a canary."""
+    _echo_json(obj.authed_client().delete_canary(canary_id))
+
+
+def main() -> None:
+    cli(prog_name="tripwire")
+
+
+if __name__ == "__main__":
+    main()

tripwire_cli/client.py

@@ -0,0 +1,162 @@
+"""HTTP client for the Tripwire REST API."""
+
+from __future__ import annotations
+
+from types import TracebackType
+from typing import Any
+
+import httpx
+
+DEFAULT_TIMEOUT = 10.0
+
+# Connecting should fail fast even when a single request is allowed a long read
+# window, so an unreachable server never hangs for the full read timeout.
+CONNECT_TIMEOUT = 5.0
+
+# `POST /canary` is synchronous and provider-minted types can take ~12s/44s/100s
+# today; the server waits up to ``CANARY_CREATE_WAIT_SECONDS`` (180s) before it
+# gives up. The client read timeout MUST stay above that window: if the client
+# abandons the request first, the server still creates the canary, the one-time
+# credential reveal is lost, and the cap-1 quota is consumed with no recovery.
+CREATE_READ_TIMEOUT = 240.0
+
+
+class ApiError(Exception):
+    """A non-2xx response, or a failure to reach the server (``status == 0``)."""
+
+    def __init__(self, status: int, detail: str):
+        super().__init__(f"{status}: {detail}")
+        self.status = status
+        self.detail = detail
+
+
+class ApiClient:
+    """Thin client over the Tripwire REST API.
+
+    Pass ``http_client`` to supply your own configured ``httpx.Client``
+    (handy for tests and custom transports); otherwise one is created.
+    """
+
+    def __init__(
+        self,
+        *,
+        base_url: str,
+        token: str | None = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        http_client: httpx.Client | None = None,
+    ):
+        self.base_url = base_url.rstrip("/")
+        self.token = token
+        # Short connect everywhere (a hung connect should fail fast); the
+        # read/write/pool budget is ``timeout``. The create path raises its
+        # read budget per-request via ``_request(timeout=...)``.
+        self._client = http_client or httpx.Client(
+            timeout=httpx.Timeout(timeout, connect=CONNECT_TIMEOUT)
+        )
+
+    def __enter__(self) -> ApiClient:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        self.close()
+
+    def close(self) -> None:
+        self._client.close()
+
+    def _headers(self) -> dict[str, str]:
+        headers = {"accept": "application/json"}
+        if self.token:
+            headers["authorization"] = f"Bearer {self.token}"
+        return headers
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        payload: dict[str, Any] | None = None,
+        *,
+        timeout: float | None = None,
+    ) -> dict[str, Any]:
+        kwargs: dict[str, Any] = {}
+        if timeout is not None:
+            # Per-request override: long read window, short connect so an
+            # unreachable server still fails fast.
+            kwargs["timeout"] = httpx.Timeout(timeout, connect=CONNECT_TIMEOUT)
+        try:
+            response = self._client.request(
+                method,
+                self.base_url + path,
+                json=payload,
+                headers=self._headers(),
+                **kwargs,
+            )
+        except httpx.RequestError as exc:
+            raise ApiError(0, f"cannot reach {self.base_url}: {exc}") from exc
+        if response.is_error:
+            raise ApiError(response.status_code, _error_detail(response))
+        if not response.content:
+            return {}
+        return response.json()
+
+    def login(self, user_id: str, password: str) -> dict[str, Any]:
+        return self._request(
+            "POST", "/auth/login", {"user_id": user_id, "password": password}
+        )
+
+    def login_start(self, email: str) -> dict[str, Any]:
+        """Begin an email-code login: the server emails a 6-digit code. The
+        response is intentionally neutral (``{"status": "ok"}``) and never
+        reveals whether the address is known. This endpoint is rate-limited, so
+        call it once per login and re-prompt for the code in-band on failure."""
+        return self._request("POST", "/auth/login/start", {"email": email})
+
+    def login_with_code(self, email: str, code: str) -> dict[str, Any]:
+        """Exchange an emailed 6-digit code for a token. A wrong/expired/used
+        code returns ``400 invalid_or_expired_code``."""
+        return self._request("POST", "/auth/login", {"email": email, "code": code})
+
+    def list_canaries(self) -> dict[str, Any]:
+        return self._request("GET", "/canary")
+
+    def create_canary(
+        self, payload: dict[str, Any], *, timeout: float | None = None
+    ) -> dict[str, Any]:
+        """Create a canary. The response carries the credential inline; this is
+        the only time it is returned, so capture it from the result.
+
+        ``timeout`` is the read timeout for this one request (defaults to
+        ``CREATE_READ_TIMEOUT``). It must stay above the server's synchronous
+        create wait window, or the client gives up while the server is still
+        provisioning and the one-time reveal is lost."""
+        return self._request(
+            "POST",
+            "/canary",
+            payload,
+            timeout=CREATE_READ_TIMEOUT if timeout is None else timeout,
+        )
+
+    def get_canary(self, canary_id: str) -> dict[str, Any]:
+        return self._request("GET", f"/canary/{canary_id}")
+
+    def deactivate_canary(self, canary_id: str) -> dict[str, Any]:
+        return self._request("POST", f"/canary/{canary_id}/deactivate")
+
+    def delete_canary(self, canary_id: str) -> dict[str, Any]:
+        return self._request("DELETE", f"/canary/{canary_id}")
+
+
+def _error_detail(response: httpx.Response) -> str:
+    """Best-effort human-readable detail from an error response: the JSON
+    ``detail`` field when present, else the raw body or status reason."""
+    try:
+        body = response.json()
+    except ValueError:
+        return response.text or response.reason_phrase
+    if isinstance(body, dict) and "detail" in body:
+        return str(body["detail"])
+    return response.text or response.reason_phrase

tripwire_cli/credentials.py

@@ -0,0 +1,68 @@
+"""Local credential cache for the Tripwire CLI.
+
+The token, server URL, and identity are kept in a single JSON file, by default
+``~/.config/tripwire/credentials.json`` (honoring ``XDG_CONFIG_HOME``).
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import json
+import os
+import stat
+from dataclasses import asdict, dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True, kw_only=True)
+class Credentials:
+    server: str
+    user_id: str
+    access_token: str
+    expires_at: int
+    role: str
+    # Optional: present for email-code logins, absent for operator
+    # (user-id/password) logins and for caches written by older CLIs.
+    email: str | None = None
+
+
+class NoCredentialsError(Exception):
+    pass
+
+
+def default_path() -> Path:
+    base = os.environ.get("XDG_CONFIG_HOME") or str(Path.home() / ".config")
+    return Path(base) / "tripwire" / "credentials.json"
+
+
+@dataclass(frozen=True)
+class CredentialStore:
+    """Read/write the cached credentials at ``path``."""
+
+    path: Path
+
+    def load(self) -> Credentials:
+        if not self.path.exists():
+            raise NoCredentialsError("not logged in (run `tripwire login`)")
+        data = json.loads(self.path.read_text())
+        # Forward-compatible: keep only the fields this CLI knows about, so an
+        # older CLI reading a cache written by a newer one does not crash on an
+        # unexpected keyword argument.
+        known = {f.name for f in dataclasses.fields(Credentials)}
+        return Credentials(**{k: v for k, v in data.items() if k in known})
+
+    def save(self, credentials: Credentials) -> Path:
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        self.path.write_text(json.dumps(asdict(credentials), indent=2))
+        self.path.chmod(stat.S_IRUSR | stat.S_IWUSR)
+        return self.path
+
+    def clear(self) -> bool:
+        if not self.path.exists():
+            return False
+        self.path.unlink()
+        return True
+
+
+def default_store() -> CredentialStore:
+    return CredentialStore(default_path())

tripwire_cli-0.2.0.dist-info/METADATA

@@ -0,0 +1,68 @@
+Metadata-Version: 2.4
+Name: tripwire-cli
+Version: 0.2.0
+Summary: Command-line client for Tripwire canaries
+Requires-Python: >=3.12
+Requires-Dist: click>=8.1
+Requires-Dist: httpx>=0.27
+Description-Content-Type: text/markdown
+
+# tripwire-cli
+
+Command-line client for [Tripwire](https://tripwire.so) canaries. Installs a
+single `tripwire` command.
+
+## Install
+
+```bash
+uv tool install --from . tripwire-cli
+```
+
+Or run without installing:
+
+```bash
+uvx --from . tripwire --help
+```
+
+## Usage
+
+```bash
+# Log in and cache a token. Defaults to passwordless email-code login: it
+# prompts for your email (defaulting to `git config user.email`) and the
+# 6-digit code emailed to you. Operators can pass --user-id / --password to use
+# the user-id + password login instead.
+tripwire login
+
+# Create a canary. The credential is returned once, in this response, so
+# capture it now. Provider-minted types (aws/anthropic/github) can take ~2 min;
+# the CLI waits and prints a progress note while it provisions.
+tripwire canaries create --type dns_label --memo "env metrics host"
+tripwire canaries create --type aws_access_key --memo "warehouse reporting key"
+
+# Inspect what you own (summaries only; the credential is never shown again).
+tripwire canaries list
+tripwire canaries get can_1234abcd
+
+# Wind one down.
+tripwire canaries deactivate can_1234abcd
+tripwire canaries delete can_1234abcd
+```
+
+`canaries` subcommands print JSON to stdout (pipe to `jq`); progress and other
+plain-text messages go to stderr, so stdout stays clean JSON. Run
+`tripwire --help` for the full reference.
+
+Supported create types are `dns_label`, `aws_access_key`, `anthropic_api_key`,
+and `github_pat`.
+
+`canaries create` accepts `--timeout <seconds>` (env `TRIPWIRE_CREATE_TIMEOUT`,
+default 240) for the per-request read timeout; it must stay above the server's
+~180s provisioning wait so the one-time credential reveal is never lost to a
+premature client timeout.
+
+## Server
+
+`login` talks to `https://tripwire.so/api/v1` by default. Set `TRIPWIRE_SERVER`
+to point at a self-hosted or test server before logging in; the server is bound
+to your token at login time. The token is cached at
+`~/.config/tripwire/credentials.json` (honoring `XDG_CONFIG_HOME`).

tripwire_cli-0.2.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+tripwire_cli/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+tripwire_cli/__main__.py,sha256=BOlVJVISJ_-zRpgR_nxg5GYdXHHzXuQp4FcZrZ-Epuk,73
+tripwire_cli/cli.py,sha256=XlBF1X2zqHyhOP7maQMpqoA74sIqh9t-ZuqevTpP5AY,12655
+tripwire_cli/client.py,sha256=-a1bsWTsUZGCeqPpV78oxYBWLlUiovWxeVNi5MZcx4E,5992
+tripwire_cli/credentials.py,sha256=FMH2XUhWku-tu3XdsdRUtWHmB5hu8Lbh4dWR4GtF_Yo,2032
+tripwire_cli-0.2.0.dist-info/METADATA,sha256=HcLl-k5lHNGGNhydcSSs-PQNH3JRek4LZaEg8-2AnKk,2225
+tripwire_cli-0.2.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+tripwire_cli-0.2.0.dist-info/entry_points.txt,sha256=9PdcjDdJygDUBO_006xoyJjTRuqb0K1SjNUgSpiw4wI,88
+tripwire_cli-0.2.0.dist-info/RECORD,,

tripwire_cli-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

tripwire_cli-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+tripwire = tripwire_cli.cli:main
+tripwire-cli = tripwire_cli.cli:main