controlzero 1.9.3__tar.gz → 1.9.4__tar.gz

{controlzero-1.9.3 → controlzero-1.9.4}/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## 1.9.4 -- 2026-06-16 (actionable E1101 / API-key-rejected message, #1254, epic gh#1247)
+
+### Fixed
+
+- **(#1254) `HostedAuthError` (E1101) is now actionable instead of an
+  opaque "API key rejected (401)".** A dead/revoked/expired/placeholder API key
+  in hosted mode used to surface a bare message that told the user neither WHY
+  nor what to do. The message now always states the key is invalid/revoked/
+  expired and how to fix it: "Generate a new API key in the dashboard (Settings
+  -> API Keys, https://app.controlzero.ai/settings/api-keys) and set
+  CONTROLZERO_API_KEY to it." When the backend sends a structured 401 body, the
+  exception preserves the coarse machine-readable `reason` (e.g.
+  `invalid_or_revoked`) and the `remediation` on the exception so programmatic
+  callers can branch while humans read the fix. The `E1101` code is unchanged.
+  All four 401 raise sites (bootstrap, bundle pull, approval request, get
+  secret) now parse the body via `HostedAuthError.from_response(...)`.
+  Enumeration-safe: the backend keeps the reason coarse (not_found / revoked /
+  expired / placeholder all collapse to `invalid_or_revoked`) so a 401 cannot be
+  used to probe which keys exist. Tests:
+  `tests/test_errors_e_codes.py::TestHostedAuthErrorActionable`.
+
 ## 1.9.3 -- 2026-06-16 (posture release: empty-bundle OBSERVE + self-explaining no-rule-match deny, epic gh#1247)
 
 The consolidated **posture release** for epic gh#1247 (customer Bryan).
@@ -76,7 +97,6 @@ second-opinion). It is deliberately **narrow and gated**:
   bundle translator -> `PolicySettings`. Local YAML policies may set
   `settings.default_on_empty`. The dashboard observe-mode indicator +
   CLI `status` line remain a separate frontend/CLI follow-up.
-
 ## 1.9.1 -- 2026-06-16 (hosted-mode local audit log P0, epic gh#1247)
 
 ### Fixed

{controlzero-1.9.3 → controlzero-1.9.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: controlzero
-Version: 1.9.3
+Version: 1.9.4
 Summary: AI agent governance: policies, audit, and observability for tool calls. Works locally with no signup.
 Project-URL: Homepage, https://controlzero.ai
 Project-URL: Documentation, https://docs.controlzero.ai

{controlzero-1.9.3 → controlzero-1.9.4}/controlzero/__init__.py

@@ -40,7 +40,7 @@ from controlzero.hitl.grant_protocol import (
 )
 from controlzero.policy_loader import load_policy
 
-__version__ = "1.9.3"
+__version__ = "1.9.4"
 
 __all__ = [
     "Client",

{controlzero-1.9.3 → controlzero-1.9.4}/controlzero/client.py

@@ -676,9 +676,11 @@ class Client:
         # Non-2xx: map status + body code to the right typed exception.
         body_code = ""
         body_msg = ""
+        err_body_dict: dict = {}
         try:
             err_body = resp.json()
             if isinstance(err_body, dict):
+                err_body_dict = err_body
                 body_code = str(err_body.get("code", "") or "")
                 body_msg = str(err_body.get("message", "") or err_body.get("error", "") or "")
         except ValueError:
@@ -717,7 +719,7 @@ class Client:
                 body_msg or "Requestor identity claim rejected by backend"
             )
         if status == 401:
-            raise HostedAuthError(body_msg or "hosted API key rejected by backend")
+            raise HostedAuthError.from_response(status, err_body_dict)
         if status == 404:
             raise HITLNotConfiguredError(
                 body_msg or "Approvals not configured for this org"
@@ -885,7 +887,11 @@ class Client:
         if status == 404:
             raise SecretNotFound(f"secret {name!r} not found")
         if status == 401:
-            raise HostedAuthError("hosted API key rejected by backend")
+            try:
+                secret_err_body = resp.json()
+            except ValueError:
+                secret_err_body = None
+            raise HostedAuthError.from_response(status, secret_err_body)
         if not (200 <= status < 300):
             raise HITLBackendUnreachableError(
                 f"GET /api/secrets/{name} returned HTTP {status}"

{controlzero-1.9.3 → controlzero-1.9.4}/controlzero/error_codes.yaml

@@ -95,11 +95,16 @@ codes:
   - code: E1101
     title: API key rejected (401)
     what: >-
-      The hosted backend rejected the API key. The key is either revoked,
-      from a different environment (test vs live), or never existed.
-    fix: >-
-      Check your dashboard for the current key under Settings → API Keys.
-      Make sure CONTROLZERO_API_KEY matches the key shown there.
+      The hosted backend rejected the API key with HTTP 401. The key is
+      unknown, revoked, expired, or a never-activated placeholder. For
+      safety the backend does not say which (so a 401 cannot be used to
+      probe which keys exist), but in every case the same fix applies:
+      the key you are using is no longer valid.
+    fix: >-
+      Generate a fresh key in the dashboard under Settings -> API Keys
+      (https://app.controlzero.ai/settings/api-keys) and set
+      CONTROLZERO_API_KEY to it. If you just rotated a key, make sure the
+      environment your agent runs in picked up the new value.
     doc: E1101-key-rejected
 
   - code: E1102

{controlzero-1.9.3 → controlzero-1.9.4}/controlzero/errors.py

@@ -28,6 +28,18 @@ from controlzero._internal.enforcer import PolicyDeniedError, PolicyDecision
 from controlzero.error_codes import ErrorCode, get as _get_error_code
 
 
+def _first_str(*values: object) -> Optional[str]:
+    """Return the first value that is a non-empty string, else None.
+
+    Used to read a field that the backend may place at the top level or
+    nested under ``error`` without crashing on unexpected types.
+    """
+    for v in values:
+        if isinstance(v, str) and v.strip():
+            return v
+    return None
+
+
 def _augment_with_code(message: str, code_key: Optional[str]) -> str:
     """Append the catalog's fix + docs URL to a raw error message.
 
@@ -137,6 +149,12 @@ class BundleSignatureError(_CZErrorMixin, Exception):
         super().__init__(_augment_with_code(message, self.E_CODE))
 
 
+_DEFAULT_AUTH_REMEDIATION = (
+    "Generate a new API key in the dashboard (Settings -> API Keys, "
+    "https://app.controlzero.ai/settings/api-keys) and set CONTROLZERO_API_KEY to it."
+)
+
+
 class HostedAuthError(_CZErrorMixin, RuntimeError):
     """Raised when the project API key is rejected by the backend
     (401/403). Maps to E1101.
@@ -144,12 +162,97 @@ class HostedAuthError(_CZErrorMixin, RuntimeError):
     This is a permanent failure: the caller supplied an invalid or
     revoked API key. Retrying with the same key will not help. The
     SDK surfaces this so the user can correct their configuration.
+
+    #1254: the bare "API key rejected (401)" gave the user no
+    idea WHY or what to do. The message now always tells the user the
+    key is invalid/revoked and how to fix it. When the backend supplies
+    a structured 401 body (``reason`` + ``remediation``), those are
+    preserved on the exception so programmatic callers can branch on
+    :attr:`reason` while humans read the actionable message.
+
+    The backend keeps ``reason`` coarse on purpose (not_found / revoked /
+    expired / placeholder all collapse to ``invalid_or_revoked``) so a
+    401 is never an enumeration oracle; the SDK does not try to refine it.
+
+    Attributes:
+        reason: coarse machine-readable reason from the backend, e.g.
+            ``"invalid_or_revoked"``. ``None`` when the backend did not
+            send a structured body (older backend).
+        remediation: copy-pasteable next step shown to the user.
     """
 
     E_CODE = "E1101"
 
-    def __init__(self, message: str = "hosted API key rejected by backend"):
-        super().__init__(_augment_with_code(message, self.E_CODE))
+    def __init__(
+        self,
+        message: Optional[str] = None,
+        *,
+        reason: Optional[str] = None,
+        remediation: Optional[str] = None,
+    ):
+        self.reason = reason
+        self.remediation = remediation or _DEFAULT_AUTH_REMEDIATION
+        if message is None:
+            message = (
+                "Your Control Zero API key was rejected by the backend "
+                "(invalid, revoked, or expired)."
+            )
+        full = f"{message} {self.remediation}"
+        super().__init__(_augment_with_code(full, self.E_CODE))
+
+    @classmethod
+    def from_response(
+        cls,
+        status_code: int,
+        body: object = None,
+        *,
+        context: str = "",
+    ) -> "HostedAuthError":
+        """Build a HostedAuthError from a backend 401/403 response.
+
+        ``body`` is the parsed JSON (a dict) when available, else None.
+        The backend may put the structured fields either at the top
+        level (``body["reason"]``) or nested under ``body["error"]``;
+        we read both. ``context`` is an optional short phrase like
+        "during bundle pull" appended to the headline so logs say which
+        request failed. Never raises on a malformed body -- a bad body
+        just yields the actionable default message.
+        """
+        reason: Optional[str] = None
+        remediation: Optional[str] = None
+        backend_msg: Optional[str] = None
+        if isinstance(body, dict):
+            err = body.get("error")
+            err_dict = err if isinstance(err, dict) else {}
+            reason = _first_str(body.get("reason"), err_dict.get("reason"))
+            remediation = _first_str(
+                body.get("remediation"), err_dict.get("remediation")
+            )
+            # The backend message can be body["message"], the nested
+            # error.message, or -- for back-compat with non-structured
+            # backends -- a plain string in the top-level "error" key
+            # (e.g. {"error": "Unauthorized"}).
+            err_str = err if isinstance(err, str) else None
+            backend_msg = _first_str(
+                body.get("message"), err_dict.get("message"), err_str
+            )
+
+        headline = (
+            "Your Control Zero API key was rejected by the backend "
+            "(invalid, revoked, or expired)."
+        )
+        if context:
+            headline = (
+                f"Your Control Zero API key was rejected by the backend "
+                f"{context} (invalid, revoked, or expired)."
+            )
+        # Prefer the backend's own human message when it is more specific
+        # than our generic headline, but always keep the headline so the
+        # user sees the "what to do" framing even with an old backend.
+        message = headline
+        if backend_msg and backend_msg.lower() not in ("invalid api key", ""):
+            message = f"{headline} (backend: {backend_msg})"
+        return cls(message, reason=reason, remediation=remediation)
 
 
 class HostedBootstrapError(_CZErrorMixin, RuntimeError):

{controlzero-1.9.3 → controlzero-1.9.4}/controlzero/hosted_policy.py

@@ -66,6 +66,20 @@ PULL_TIMEOUT_S = 5.0
 MAX_BUNDLE_BYTES = 16 * 1024 * 1024
 
 
+def _try_json(resp: object) -> object:
+    """Best-effort parse of an httpx response body as JSON.
+
+    Returns the decoded object on success, or ``None`` on any failure
+    (non-JSON body, empty body, missing ``.json``). Never raises -- a
+    structured 401 body is a bonus, not a requirement, so a malformed
+    body must not mask the underlying auth error (#1254).
+    """
+    try:
+        return resp.json()  # type: ignore[attr-defined]
+    except Exception:  # noqa: BLE001
+        return None
+
+
 def get_api_url() -> str:
     """Resolve the Control Zero API base URL."""
     return os.environ.get("CONTROLZERO_API_URL", DEFAULT_API_URL).rstrip("/")
@@ -230,10 +244,7 @@ def fetch_bootstrap(api_key: str, api_url: Optional[str] = None) -> BootstrapKey
         ) from exc
 
     if resp.status_code in (401, 403):
-        raise HostedAuthError(
-            "Control Zero API key rejected by backend. Check that "
-            "CONTROLZERO_API_KEY is a valid cz_live_ or cz_test_ project key."
-        )
+        raise HostedAuthError.from_response(resp.status_code, _try_json(resp))
     if resp.status_code >= 400:
         raise HostedBootstrapError(
             f"bootstrap returned HTTP {resp.status_code}: {resp.text[:500]}"
@@ -370,8 +381,8 @@ def pull_bundle(
     if resp.status_code == 304:
         return None
     if resp.status_code in (401, 403):
-        raise HostedAuthError(
-            "Control Zero API key rejected during bundle pull."
+        raise HostedAuthError.from_response(
+            resp.status_code, _try_json(resp), context="during bundle pull"
         )
     if resp.status_code >= 400:
         raise HostedBootstrapError(

{controlzero-1.9.3 → controlzero-1.9.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "controlzero"
-version = "1.9.3"
+version = "1.9.4"
 description = "AI agent governance: policies, audit, and observability for tool calls. Works locally with no signup."
 readme = "README.md"
 license = {text = "Apache-2.0"}