burnedsecret-cli 1.0.0__py3-none-any.whl

burnedsecret_cli/__init__.py

@@ -0,0 +1,3 @@
+"""burnedsecret-cli — command-line interface for the burnedsecret.com API."""
+
+__version__ = "1.0.0"  # semver (D-04): CLI major pinned to SDK major

burnedsecret_cli/auth_flow.py

@@ -0,0 +1,369 @@
+"""The reusable D-10 PKCE + loopback browser-login recipe (client half).
+
+This module owns the terminal side of ``bs auth login``: it performs an
+RFC 7636 PKCE S256 + RFC 8252 loopback-redirect flow against the web
+``/cli-auth`` consent page (plan 11-02) and the ``POST /v1/cli-auth/exchange``
+endpoint (plan 11-01), and returns a freshly minted long-lived API key.
+
+Design constraints (security-critical):
+    * stdlib ONLY — no HTTP client dependency. The two ``/v1/cli-auth/*`` calls
+      this module makes use ``urllib.request``; the SDK owns its own transport
+      for the business endpoints and is intentionally not reused here.
+    * The API key is returned ONLY in the exchange RESPONSE BODY. It is never
+      printed and never placed in any URL. The browser callback carries only
+      ``code`` + ``state`` (and, on failure, ``error``).
+    * The single-use ``code`` (60s, PKCE-bound) and the long-lived ``api_key``
+      it is exchanged for are kept terminologically and lifecycle-wise distinct.
+    * The returned ``state`` is compared against the sent CSRF ``state``; a
+      mismatch aborts login and stores nothing (the caller never sees a key).
+
+Flow (``run_login``):
+    1. Generate a CSRF ``state``, a PKCE ``(verifier, challenge)`` pair, and pick
+       a free loopback port.
+    2. Start a one-shot ``127.0.0.1:<port>`` HTTP server (in a thread, with a
+       timeout) that captures ``?code=&state=`` / ``?error=``, validates the
+       returned ``state``, serves a terminal-themed "you can close this tab"
+       page, and shuts down after one request.
+    3. Open the browser to the web ``/cli-auth`` authorize URL (carrying the
+       loopback callback, the CSRF state, and the S256 challenge). The URL is
+       also echoed to STDERR for the headless / can't-open-browser fallback.
+    4. Exchange the captured ``code`` + the PKCE ``verifier`` at
+       ``/v1/cli-auth/exchange`` and return ``{api_key, key_prefix, name,
+       hostname}``.
+"""
+from __future__ import annotations
+
+import base64
+import hashlib
+import http.server
+import json
+import secrets
+import socket
+import sys
+import threading
+import urllib.error
+import urllib.parse
+import urllib.request
+from dataclasses import dataclass, field
+from typing import Optional
+
+# How long we wait for the browser round-trip before giving up. The server's
+# single-use code TTL is 60s; we allow a little longer for the human to land on
+# the consent page and click Authorize.
+_LOGIN_TIMEOUT_SECONDS = 120
+
+
+class AuthFlowError(Exception):
+    """A recoverable login-flow failure (CSRF mismatch, timeout, exchange error).
+
+    Carries a human-facing message only; never embeds the verifier, the code,
+    or the minted key.
+    """
+
+
+def pkce_pair() -> tuple[str, str]:
+    """Return an RFC 7636 ``(code_verifier, code_challenge)`` S256 pair.
+
+    ``verifier`` = base64url(32 random bytes) with padding stripped.
+    ``challenge`` = base64url(sha256(verifier)) with padding stripped — exactly
+    the transform the server's ``_compute_pkce_challenge`` recomputes and
+    constant-time compares against the stored challenge.
+    """
+    verifier = base64.urlsafe_b64encode(secrets.token_bytes(32)).rstrip(b"=").decode("ascii")
+    digest = hashlib.sha256(verifier.encode("ascii")).digest()
+    challenge = base64.urlsafe_b64encode(digest).rstrip(b"=").decode("ascii")
+    return verifier, challenge
+
+
+def free_port() -> int:
+    """Bind ``127.0.0.1:0`` to grab an OS-assigned free port, then release it.
+
+    There is an inherent TOCTOU window between releasing the port here and the
+    one-shot server re-binding it; in practice this is fine for a same-machine,
+    same-process loopback login and matches the RFC 8252 native-app pattern.
+    """
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
+        sock.bind(("127.0.0.1", 0))
+        return sock.getsockname()[1]
+
+
+def web_origin_from_base_url(base_url: Optional[str]) -> str:
+    """Derive the web origin (scheme://host[:port]) hosting ``/cli-auth``.
+
+    ``base_url`` is the configured API base (e.g.
+    ``https://burnedsecret.com/api/v1``). The web consent page lives at the same
+    origin's ``/cli-auth`` path, so we strip the API path entirely and keep only
+    the origin. ``None`` (no override) maps to the production origin.
+    """
+    if not base_url:
+        return "https://burnedsecret.com"
+    parsed = urllib.parse.urlsplit(base_url)
+    if not parsed.scheme or not parsed.netloc:
+        # Not a parseable URL — fall back to production rather than build a
+        # malformed authorize URL.
+        return "https://burnedsecret.com"
+    return f"{parsed.scheme}://{parsed.netloc}"
+
+
+def api_base_from_base_url(base_url: Optional[str]) -> str:
+    """Derive the ``/api/v1`` base used for the exchange POST.
+
+    Honors an explicit configured override; otherwise returns the production
+    ``https://burnedsecret.com/api/v1`` (matching the SDK's own default). The
+    returned value has no trailing slash.
+    """
+    if base_url:
+        return base_url.rstrip("/")
+    return "https://burnedsecret.com/api/v1"
+
+
+# Terminal-themed confirmation page served to the browser after a successful
+# (or failed) callback. Self-contained, no external assets.
+_SUCCESS_HTML = """<!doctype html>
+<html lang="en"><head><meta charset="utf-8">
+<title>BurnedSecret CLI</title>
+<style>
+  html,body{height:100%;margin:0}
+  body{display:flex;align-items:center;justify-content:center;
+       background:#0b0f10;color:#d6f5d6;
+       font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace}
+  .card{text-align:center;padding:2rem 2.5rem;border:1px solid #1f2d1f;
+        border-radius:10px;background:#0e1412}
+  .ok{font-size:1.4rem;color:#7CFC7C}
+  .sub{margin-top:.5rem;color:#8aa88a;font-size:.95rem}
+</style></head>
+<body><div class="card">
+  <div class="ok">&#10003; Authorized</div>
+  <div class="sub">Return to your terminal &mdash; you can close this tab.</div>
+</div></body></html>"""
+
+_ERROR_HTML = """<!doctype html>
+<html lang="en"><head><meta charset="utf-8">
+<title>BurnedSecret CLI</title>
+<style>
+  html,body{height:100%;margin:0}
+  body{display:flex;align-items:center;justify-content:center;
+       background:#0b0f10;color:#f5d6d6;
+       font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace}
+  .card{text-align:center;padding:2rem 2.5rem;border:1px solid #2d1f1f;
+        border-radius:10px;background:#140e0e}
+  .err{font-size:1.4rem;color:#FC7C7C}
+  .sub{margin-top:.5rem;color:#a88a8a;font-size:.95rem}
+</style></head>
+<body><div class="card">
+  <div class="err">&#10007; Login failed</div>
+  <div class="sub">Return to your terminal for details &mdash; you can close this tab.</div>
+</div></body></html>"""
+
+
+@dataclass
+class _CallbackResult:
+    """Mutable holder the one-shot handler writes the captured params into."""
+
+    code: Optional[str] = None
+    error: Optional[str] = None
+    state_ok: bool = False
+    received: threading.Event = field(default_factory=threading.Event)
+
+
+def _make_handler(expected_state: str, result: _CallbackResult):
+    """Build a one-shot ``BaseHTTPRequestHandler`` bound to this login attempt.
+
+    Captures ``code``/``state``/``error`` from the first GET, validates the CSRF
+    ``state`` against ``expected_state``, serves the confirmation page, and signals
+    ``result.received``. Subsequent requests (favicon, etc.) get a bare 204.
+    """
+
+    class _Handler(http.server.BaseHTTPRequestHandler):
+        # Silence the default stderr request logging (it would pollute the
+        # CLI's stderr discipline with raw HTTP log lines).
+        def log_message(self, *args, **kwargs):  # noqa: D401, ANN001
+            return
+
+        def _respond(self, status: int, html: str) -> None:
+            body = html.encode("utf-8")
+            self.send_response(status)
+            self.send_header("Content-Type", "text/html; charset=utf-8")
+            self.send_header("Content-Length", str(len(body)))
+            self.end_headers()
+            self.wfile.write(body)
+
+        def do_GET(self) -> None:  # noqa: N802 (http.server API)
+            parsed = urllib.parse.urlsplit(self.path)
+            # Ignore everything but the callback root (e.g. /favicon.ico).
+            if result.received.is_set():
+                self._respond(204, "")
+                return
+            params = urllib.parse.parse_qs(parsed.query)
+            error = params.get("error", [None])[0]
+            code = params.get("code", [None])[0]
+            returned_state = params.get("state", [None])[0]
+
+            if error:
+                result.error = error
+                self._respond(400, _ERROR_HTML)
+                result.received.set()
+                return
+
+            # CSRF: the returned state MUST match the one we sent. A mismatch is
+            # a hard abort — we capture NO code, so no exchange happens.
+            if returned_state != expected_state:
+                result.state_ok = False
+                result.error = "state_mismatch"
+                self._respond(400, _ERROR_HTML)
+                result.received.set()
+                return
+
+            if not code:
+                result.error = "missing_code"
+                self._respond(400, _ERROR_HTML)
+                result.received.set()
+                return
+
+            result.state_ok = True
+            result.code = code
+            self._respond(200, _SUCCESS_HTML)
+            result.received.set()
+
+    return _Handler
+
+
+def _exchange_code(api_base: str, code: str, code_verifier: str) -> dict:
+    """POST ``{code, code_verifier}`` to ``/cli-auth/exchange``; return its body.
+
+    Returns the parsed JSON ``{api_key, key_prefix, name}``. Raises
+    :class:`AuthFlowError` on any HTTP/transport/shape failure — never leaking
+    the verifier or code into the message.
+    """
+    url = f"{api_base}/cli-auth/exchange"
+    payload = json.dumps({"code": code, "code_verifier": code_verifier}).encode("utf-8")
+    req = urllib.request.Request(
+        url,
+        data=payload,
+        headers={"Content-Type": "application/json", "Accept": "application/json"},
+        method="POST",
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=30) as resp:  # noqa: S310 (https URL)
+            raw = resp.read()
+    except urllib.error.HTTPError as exc:  # server said no (400 INVALID_CODE, etc.)
+        raise AuthFlowError(
+            "Code exchange was rejected by the server "
+            f"(HTTP {exc.code}). The login code may have expired — retry `bs auth login`."
+        ) from None
+    except urllib.error.URLError as exc:
+        raise AuthFlowError(f"Could not reach the exchange endpoint: {exc.reason}") from None
+
+    try:
+        body = json.loads(raw.decode("utf-8"))
+    except (ValueError, UnicodeDecodeError):
+        raise AuthFlowError("Exchange response was not valid JSON.") from None
+
+    api_key = body.get("api_key")
+    if not isinstance(api_key, str) or not api_key:
+        raise AuthFlowError("Exchange response did not contain an api_key.")
+    return body
+
+
+def build_authorize_url(
+    web_origin: str,
+    callback: str,
+    state: str,
+    challenge: str,
+    hostname: str,
+) -> str:
+    """Construct the web ``/cli-auth`` authorize URL the browser is sent to.
+
+    Carries the loopback ``callback``, the CSRF ``state``, the PKCE S256
+    ``code_challenge`` (+ method), and the ``hostname`` to label the key. It
+    deliberately carries NO secret — only the public challenge and state.
+    """
+    query = urllib.parse.urlencode(
+        {
+            "callback": callback,
+            "state": state,
+            "code_challenge": challenge,
+            "code_challenge_method": "S256",
+            "hostname": hostname,
+        }
+    )
+    return f"{web_origin}/cli-auth?{query}"
+
+
+def run_login(
+    base_url: Optional[str],
+    hostname: str,
+    *,
+    open_browser: bool = True,
+    timeout: int = _LOGIN_TIMEOUT_SECONDS,
+) -> dict:
+    """Run the full PKCE + loopback + exchange login and return the minted key.
+
+    ``base_url`` is the configured API base (``None`` → production). ``hostname``
+    labels the minted key ("CLI - <hostname>"). Returns
+    ``{api_key, key_prefix, name, hostname}`` on success.
+
+    Raises :class:`AuthFlowError` on CSRF/state mismatch, browser ``error=``
+    callback, timeout, or an exchange failure — in every failure path NO key is
+    returned, so the caller stores nothing.
+    """
+    verifier, challenge = pkce_pair()
+    state = secrets.token_urlsafe(24)
+    port = free_port()
+    callback = f"http://127.0.0.1:{port}"
+
+    web_origin = web_origin_from_base_url(base_url)
+    api_base = api_base_from_base_url(base_url)
+    authorize_url = build_authorize_url(web_origin, callback, state, challenge, hostname)
+
+    result = _CallbackResult()
+    handler = _make_handler(state, result)
+    httpd = http.server.HTTPServer(("127.0.0.1", port), handler)
+    httpd.timeout = 1  # poll granularity for the serve loop
+
+    def _serve() -> None:
+        # Serve requests until the callback is received (or the thread is asked
+        # to stop via the daemon flag at interpreter exit).
+        while not result.received.is_set():
+            httpd.handle_request()
+
+    server_thread = threading.Thread(target=_serve, daemon=True)
+    server_thread.start()
+
+    # Always surface the URL on STDERR — both as the headless fallback and so a
+    # user whose browser didn't open can paste it manually.
+    print(f"Opening your browser to authorize this CLI:\n  {authorize_url}", file=sys.stderr)
+    if open_browser:
+        import webbrowser
+
+        try:
+            webbrowser.open(authorize_url)
+        except Exception:  # noqa: BLE001 — headless: the URL is already on stderr
+            pass
+
+    got_it = result.received.wait(timeout=timeout)
+    # Stop the server loop regardless of outcome.
+    httpd.server_close()
+
+    if not got_it:
+        raise AuthFlowError(
+            f"Timed out after {timeout}s waiting for browser authorization. "
+            "Retry `bs auth login`."
+        )
+    if result.error == "state_mismatch":
+        raise AuthFlowError(
+            "CSRF state mismatch — the browser callback did not match this login "
+            "request. Aborted; nothing was stored."
+        )
+    if result.error:
+        raise AuthFlowError(f"Authorization failed: {result.error}.")
+    if not result.code:
+        raise AuthFlowError("No authorization code was returned.")
+
+    body = _exchange_code(api_base, result.code, verifier)
+    return {
+        "api_key": body["api_key"],
+        "key_prefix": body.get("key_prefix"),
+        "name": body.get("name"),
+        "hostname": hostname,
+    }

burnedsecret_cli/client_factory.py

@@ -0,0 +1,41 @@
+"""Build a shipped-SDK ``BurnedSecret`` client from resolved config.
+
+The CRITICAL invariant: when the user has NOT configured a ``base_url``,
+construct the client WITHOUT a ``base_url`` kwarg so the SDK applies its own
+``_DEFAULT_BASE`` (``https://burnedsecret.com/api/v1`` — with ``/v1``). We never
+pass a hardcoded ``.../api`` (no ``/v1``) string; that would 404 against the
+live API. When the user DID configure an explicit ``base_url``, we honor it.
+"""
+from __future__ import annotations
+
+from typing import Optional
+
+from burnedsecret import BurnedSecret
+
+from .config import resolve_api_key, resolve_base_url
+from .output import ExitCode, exit_with
+
+
+def build_client(cfg: dict, profile: str) -> BurnedSecret:
+    """Construct a :class:`BurnedSecret` for ``profile`` using ``cfg``.
+
+    Resolves the API key (env > config) and base URL (profile > global > None).
+    Passes ``base_url`` to the constructor ONLY when an explicit override is
+    configured, so the SDK's correct ``/v1`` default applies otherwise.
+
+    Exits with :attr:`ExitCode.AUTH` and a friendly message if no API key is
+    resolved.
+    """
+    api_key: Optional[str] = resolve_api_key(cfg, profile)
+    if not api_key:
+        exit_with(
+            "Not authenticated — run `bs auth login` or set "
+            "BURNEDSECRET_API_KEY.",
+            ExitCode.AUTH,
+        )
+
+    base_url = resolve_base_url(cfg, profile)
+    if base_url:
+        return BurnedSecret(api_key=api_key, base_url=base_url)
+    # No override → let the SDK apply its own _DEFAULT_BASE (.../api/v1).
+    return BurnedSecret(api_key=api_key)

burnedsecret_cli/commands/__init__.py

@@ -0,0 +1 @@
+"""Concrete CLI command groups (secret/request in plan 04; key/auth in plan 05)."""

burnedsecret_cli/commands/_ttl.py

@@ -0,0 +1,77 @@
+"""Shared TTL handling for ``bs secret`` and ``bs request`` (Conflict 3 / Pitfall 5).
+
+The SDK's ``ttl=`` argument accepts ONLY the exact seconds in
+``burnedsecret.client._VALID_TTLS == {300, 3600, 86400, 604800}``. Anything else
+raises ``ValueError`` inside the SDK. The CLI exposes those four values as a
+friendly 4-member Typer ``Enum`` (``5m``/``1h``/``1d``/``7d``), and translates
+the human-facing config knob ``[global].default_ttl_days`` (in DAYS) into one of
+those exact seconds — refusing day values that have no member rather than
+silently computing ``days * 86400`` (which would hand the SDK an invalid TTL).
+"""
+from __future__ import annotations
+
+import enum
+
+from ..output import ExitCode, exit_with
+
+# Default when neither --ttl nor config default_ttl_days is set: 1 day.
+DEFAULT_TTL_SECONDS = 86400
+
+
+class Ttl(str, enum.Enum):
+    """The four TTL choices the SDK accepts, as human-friendly labels.
+
+    ``.value`` is the label (what Typer parses / shows); ``.seconds`` is the
+    exact SDK seconds. A bad CLI value fails at parse time (exit 2) because
+    Typer validates against the enum members.
+    """
+
+    FIVE_MIN = "5m"
+    ONE_HOUR = "1h"
+    ONE_DAY = "1d"
+    SEVEN_DAYS = "7d"
+
+    @property
+    def seconds(self) -> int:
+        return _TTL_TO_SECONDS[self]
+
+
+_TTL_TO_SECONDS: dict[Ttl, int] = {
+    Ttl.FIVE_MIN: 300,
+    Ttl.ONE_HOUR: 3600,
+    Ttl.ONE_DAY: 86400,
+    Ttl.SEVEN_DAYS: 604800,
+}
+
+# The ONLY whole-day-expressible TTL members. 5m/1h are sub-day, so a
+# ``default_ttl_days`` of anything other than 1 or 7 has no valid mapping.
+_DAY_DEFAULT_MAP: dict[int, int] = {1: 86400, 7: 604800}
+
+
+def resolve_ttl_seconds(ttl: Ttl | None, cfg: dict) -> int:
+    """Resolve the effective TTL in SDK seconds.
+
+    Priority: an explicit ``--ttl`` enum (``ttl``) wins; otherwise the config's
+    ``[global].default_ttl_days`` is mapped through :data:`_DAY_DEFAULT_MAP`;
+    otherwise :data:`DEFAULT_TTL_SECONDS` (1 day).
+
+    A ``default_ttl_days`` present but NOT in ``{1, 7}`` is a configuration
+    error: exit ``INVALID_ARGS`` WITHOUT contacting the SDK (never silently
+    forward ``days * 86400``).
+    """
+    if ttl is not None:
+        return ttl.seconds
+
+    global_table = cfg.get("global")
+    if isinstance(global_table, dict) and "default_ttl_days" in global_table:
+        days = global_table.get("default_ttl_days")
+        if days in _DAY_DEFAULT_MAP:
+            return _DAY_DEFAULT_MAP[days]
+        exit_with(
+            f"Invalid [global].default_ttl_days = {days!r}: only "
+            f"{sorted(_DAY_DEFAULT_MAP)} (whole days) are supported. "
+            "Use --ttl for 5m/1h.",
+            ExitCode.INVALID_ARGS,
+        )
+
+    return DEFAULT_TTL_SECONDS