cortexdb-cli 0.6.0__py3-none-any.whl → 0.7.0__py3-none-any.whl

cortexdb_cli/__init__.py

@@ -1,3 +1,3 @@
 """CortexDB CLI - command-line interface for the v1 memory API."""
 
-__version__ = "0.6.0"
+__version__ = "0.7.0"

cortexdb_cli/client.py

@@ -2,8 +2,14 @@
 
 Thin wrapper around httpx that reads credentials + endpoint from the CLI
 context and stamps every request with both `Authorization: Bearer ...` and
-`X-Cortex-Actor: ...`. The actor header is mandatory on v1 - missing it
-returns 401 ACTOR_MISMATCH no matter how valid the token is.
+`X-Cortex-Actor: ...`. The actor header is mandatory on v1 for a token
+whose issuer does not map its subject - missing it returns 401
+ACTOR_MISMATCH no matter how valid the token is.
+
+`X-Cortex-Break-Glass` is added when the context carries a break-glass
+reason (`--break-glass`, see `cortexdb_cli.common`): the operator key's
+header for a data read the deployment's or the tenant's
+`CORTEX_OPERATOR_DATA_READS=deny` refuses without it.
 
 We deliberately don't depend on the cortexdbai SDK: keeping the CLI a
 straight HTTP client makes the install fast and lets us pin httpx
@@ -14,13 +20,72 @@ from __future__ import annotations
 
 from contextlib import contextmanager
 from typing import Any, Generator
+from urllib.parse import quote
 
+import click
 import httpx
 
 from cortexdb_cli import __version__
 
 DEFAULT_ENDPOINT = "https://api-v1.cortexdb.ai"
 
+BREAK_GLASS_HEADER = "X-Cortex-Break-Glass"
+BREAK_GLASS_REASONS = (
+    "incident",
+    "legal",
+    "support",
+    "security",
+    "migration",
+    "restore",
+    "other",
+)
+_TICKET_CHARS = set("abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789._:-")
+
+
+def break_glass_header(reason: str, ticket: str | None, note: str | None = None) -> str:
+    """The `X-Cortex-Break-Glass` value (`reason=<r>; ticket=<t>[; note=<pct>]`).
+
+    Checked here as the server checks it (a malformed header is 400
+    `INVALID_HEADER` in every mode), so a typo is a usage error before
+    anything is sent. A `reason` that already holds `key=value` fields is
+    taken as the whole header.
+    """
+    if "=" in reason:
+        value = reason.strip()
+    else:
+        if reason not in BREAK_GLASS_REASONS:
+            raise ValueError(
+                f"--break-glass is one of {', '.join(BREAK_GLASS_REASONS)}, not {reason!r}"
+            )
+        if not ticket:
+            raise ValueError("--break-glass needs --break-glass-ticket (the case reference)")
+        if not (1 <= len(ticket) <= 64) or not set(ticket) <= _TICKET_CHARS:
+            raise ValueError("--break-glass-ticket is 1 to 64 characters of [A-Za-z0-9._:-]")
+        value = f"reason={reason}; ticket={ticket}"
+        if note:
+            if len(note.encode("utf-8")) > 256:
+                raise ValueError("--break-glass-note is at most 256 bytes")
+            value += f"; note={quote(note, safe='')}"
+    if len(value) > 512 or not value.isascii():
+        raise ValueError("the break-glass header is at most 512 ASCII bytes")
+    return value
+
+
+def request_headers(ctx: dict[str, Any]) -> dict[str, str]:
+    """The headers the CLI context adds to every request beyond auth."""
+    headers: dict[str, str] = {}
+    reason = ctx.get("break_glass")
+    if reason:
+        try:
+            headers[BREAK_GLASS_HEADER] = break_glass_header(
+                str(reason), ctx.get("break_glass_ticket"), ctx.get("break_glass_note")
+            )
+        except ValueError as exc:
+            raise click.UsageError(str(exc)) from None
+    elif ctx.get("break_glass_ticket") or ctx.get("break_glass_note"):
+        raise click.UsageError("--break-glass-ticket and --break-glass-note need --break-glass REASON")
+    return headers
+
 
 class CortexClient:
     """Synchronous HTTP client for the CortexDB v1 API."""
@@ -31,6 +96,7 @@ class CortexClient:
         api_key: str,
         actor: str = "",
         timeout: float = 30.0,
+        extra_headers: dict[str, str] | None = None,
     ) -> None:
         self.endpoint = endpoint.rstrip("/")
         self.api_key = api_key
@@ -43,6 +109,7 @@ class CortexClient:
             headers["Authorization"] = f"Bearer {api_key}"
         if actor:
             headers["X-Cortex-Actor"] = actor
+        headers.update(extra_headers or {})
         self._http = httpx.Client(
             base_url=self.endpoint,
             headers=headers,
@@ -52,27 +119,53 @@ class CortexClient:
     def close(self) -> None:
         self._http.close()
 
-    def get(self, path: str, params: dict[str, Any] | None = None) -> httpx.Response:
-        return self._http.get(path, params=params)
+    def get(
+        self,
+        path: str,
+        params: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> httpx.Response:
+        return self._http.get(path, params=params, headers=headers)
 
     def post(
         self,
         path: str,
         json: dict[str, Any] | None = None,
         params: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+        content: bytes | None = None,
     ) -> httpx.Response:
-        return self._http.post(path, json=json, params=params)
+        if content is not None:
+            # A raw body (`code import-scip`, `code import-index`). Before
+            # 0.7.0 `post` took no `content`, so those commands raised
+            # TypeError before sending anything.
+            return self._http.post(path, content=content, params=params, headers=headers)
+        return self._http.post(path, json=json, params=params, headers=headers)
 
     def put(
         self,
         path: str,
         json: dict[str, Any] | None = None,
         params: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
     ) -> httpx.Response:
-        return self._http.put(path, json=json, params=params)
+        return self._http.put(path, json=json, params=params, headers=headers)
+
+    def delete(
+        self,
+        path: str,
+        params: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> httpx.Response:
+        return self._http.delete(path, params=params, headers=headers)
+
+    def request(self, method: str, path: str, **kwargs: Any) -> httpx.Response:
+        return self._http.request(method, path, **kwargs)
+
 
-    def delete(self, path: str, params: dict[str, Any] | None = None) -> httpx.Response:
-        return self._http.delete(path, params=params)
+def path_segment(value: str) -> str:
+    """`value` as one URL path segment: `/` (a scope path's) is sent as %2F."""
+    return quote(value, safe=":@!$&'()*+,;=")
 
 
 def signup(endpoint: str = DEFAULT_ENDPOINT, timeout: float = 30.0) -> dict[str, Any]:
@@ -87,12 +180,14 @@ def signup(endpoint: str = DEFAULT_ENDPOINT, timeout: float = 30.0) -> dict[str,
 
 
 @contextmanager
-def get_client(ctx: dict[str, Any]) -> Generator[CortexClient, None, None]:
+def get_client(ctx: dict[str, Any], timeout: float = 30.0) -> Generator[CortexClient, None, None]:
     """Create a CortexClient from CLI context."""
     client = CortexClient(
         endpoint=ctx.get("endpoint", DEFAULT_ENDPOINT),
         api_key=ctx.get("api_key", ""),
         actor=ctx.get("actor", ""),
+        timeout=timeout,
+        extra_headers=request_headers(ctx),
     )
     try:
         yield client