controlzero 1.9.2__tar.gz → 1.9.4__tar.gz

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

@@ -1,5 +1,102 @@
 # 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).
+Three customer-visible behaviors land together so the engine's "what
+happens when a tool isn't covered by a rule" story is coherent across
+both SDKs and the backend:
+
+1. **Empty bundle -> OBSERVE** (was the only content of the superseded
+   1.9.2-observe draft).
+2. **Non-empty no-rule-match deny is now self-explaining** (folds in the
+   Python-only fix from gh#1257, which is superseded by this release).
+3. The backend `default_on_empty` knob on the bundle handler.
+
+### Fixed
+
+- **Hosted no-rule-match deny is now self-explaining (folds gh#1257).** A
+  non-empty bundle with `default_action=deny` and zero rule matches (the
+  exact shape of Bryan's "Db read only" allow-list, which excludes
+  `bash`) used to deny with the bare, bug-looking message
+  `No matching policy rule (fail-closed default)` -- no path out. The
+  deny reason now NAMES the unmatched action (e.g. `bash:find`) and the
+  exact remediation (add a catch-all `allow: '*'`, allow the specific
+  action, or flip the project/org default to allow) and tells the user
+  to do it in the Control Zero dashboard. `reason_code` stays
+  `NO_RULE_MATCH`; the legacy `fail-closed default` substring is retained
+  for any downstream regex consumer. The empty-bundle OBSERVE catch-all
+  matches FIRST, so a genuinely-empty bundle still observes and never
+  reaches this deny -- the two behaviors compose cleanly. Regression
+  tests in `tests/test_default_action.py`
+  (`test_1247_no_rule_match_deny_*`).
+
+### Changed
+
+A genuinely-EMPTY hosted bundle -- one that resolved successfully but has
+zero attached/active policies -- now defaults to **OBSERVE** (allow +
+audit + a loud "monitoring, not enforcing" signal) instead of the old
+day-one deny-brick. A fresh hosted project no longer blocks every tool
+call before the operator has authored a single rule; instead Control
+Zero allows the call through and audits it, loudly flagged, so the
+operator can see the engine is wired up and watching, then attach a
+policy to start enforcing.
+
+This is a founder-approved posture refinement (validated by a 4-lens
+second-opinion). It is deliberately **narrow and gated**:
+
+- **Only the genuinely-empty, successfully-resolved case observes.** A
+  non-empty bundle whose rules evaluate but nothing matches still
+  **denies** (`NO_RULE_MATCH`, `default_action` canonical deny) --
+  authored allow-lists stay secure. A bundle RESOLUTION ERROR / failed
+  pull / RLS / auth / decrypt failure still **fails closed** (deny,
+  `BUNDLE_MISSING`, honoring `default_on_missing`). Observe mode can
+  never mask a resolution error as an allow.
+- **The empty-vs-error boundary is structural, not a runtime flag.** The
+  empty path (`translate_to_local_policy`, reached only on successful
+  resolution) and the error path (`make_bundle_missing_policy`, reached
+  only on resolution failure) are separate functions with separate
+  reason codes, so they cannot be confused.
+
+### Added
+
+- **New `reason_code=OBSERVE_MODE_NO_POLICY`** and synthetic policy_id
+  `synthetic:OBSERVE_MODE_NO_POLICY` for the empty-bundle observe allow,
+  distinct from `NO_ACTIVE_POLICIES` (the deny/warn/allow empty postures)
+  and `BUNDLE_MISSING` (the fail-closed resolution-error path).
+- **`PolicyDecision.observe: bool`** -- True only on an observe-mode
+  allow. The CLI `guard` output now prints a loud yellow "OBSERVE MODE:
+  monitoring, not enforcing" line so an observe allow can never be
+  mistaken for a normal rule-driven allow. Gated strictly on the
+  reason_code, so no user-authored rule can ever set it.
+- **New `default_on_empty` knob** (`observe`|`deny`|`warn`|`allow`,
+  canonical `observe`), separate from `default_action`. An operator can
+  declare allow-list-vs-deny-list intent for the empty case instead of
+  it being inferred. Plumbed end-to-end: backend bundle payload ->
+  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.2 → controlzero-1.9.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: controlzero
-Version: 1.9.2
+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.2 → 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.2"
+__version__ = "1.9.4"
 
 __all__ = [
     "Client",

{controlzero-1.9.2 → controlzero-1.9.4}/controlzero/_internal/bundle.py

@@ -493,9 +493,11 @@ def translate_to_local_policy(payload: dict) -> dict:
     # the canonical-default fallback (one source of truth).
     from controlzero._internal.enforcer import (
         DEFAULT_BUNDLE_ACTION,
+        DEFAULT_BUNDLE_ON_EMPTY,
         DEFAULT_BUNDLE_ON_MISSING,
         DEFAULT_BUNDLE_ON_TAMPER,
         VALID_DEFAULT_ACTIONS,
+        VALID_DEFAULT_ON_EMPTY,
         VALID_DEFAULT_ON_MISSING,
         VALID_DEFAULT_ON_TAMPER,
     )
@@ -508,6 +510,19 @@ def translate_to_local_policy(payload: dict) -> dict:
     if default_on_missing not in VALID_DEFAULT_ON_MISSING:
         default_on_missing = DEFAULT_BUNDLE_ON_MISSING
 
+    # default_on_empty (#1247 item 3): empty-bundle posture, resolved
+    # server-side org->project->canonical("observe"). Separate from
+    # default_action so an authored allow-list (no-match -> deny) and an
+    # empty project (observe) do not have to share one knob. Unknown /
+    # absent values coerce to the canonical "observe" so a fresh hosted
+    # project is observe-by-default instead of bricked day-one. NOTE:
+    # this knob is read ONLY here, on the SUCCESSFUL-resolution empty
+    # branch below -- the resolution-ERROR path (make_bundle_missing_
+    # policy) does not consult it and still fails closed.
+    default_on_empty = payload.get("default_on_empty")
+    if default_on_empty not in VALID_DEFAULT_ON_EMPTY:
+        default_on_empty = DEFAULT_BUNDLE_ON_EMPTY
+
     default_on_tamper = payload.get("default_on_tamper")
     if default_on_tamper not in VALID_DEFAULT_ON_TAMPER:
         default_on_tamper = DEFAULT_BUNDLE_ON_TAMPER
@@ -536,39 +551,69 @@ def translate_to_local_policy(payload: dict) -> dict:
                 flat.append(translated)
 
     if not flat:
-        # Empty policy set: synthetic catchall rule. The effect
-        # mirrors the bundle-level default_action so "empty bundle"
-        # continues to deliver the operator's chosen posture. Prior
-        # to #228 Phase 2 this was hard-coded to deny; now an org
-        # that ships an empty-bundle-with-default=allow gets the
-        # expected allow (with the same NO_ACTIVE_POLICIES
-        # reason_code so dashboards still bucket it as "nothing
-        # attached").
+        # Empty policy set (RESOLVED SUCCESSFULLY, zero translatable
+        # rules): synthetic catch-all rule whose posture is driven by
+        # default_on_empty (#1247 item 3 / #1252), NOT default_action.
+        #
+        # Why a separate knob: default_action governs the NON-EMPTY
+        # no-match path -- an org that authored an allow-list wants that
+        # to stay deny. But an org that has attached NOTHING YET should
+        # not be bricked day-one. The founder-approved refinement makes
+        # the genuinely-empty case OBSERVE by default: the call is
+        # ALLOWED THROUGH (effect="allow") but loudly flagged as
+        # monitoring-only (reason_code=OBSERVE_MODE_NO_POLICY, which the
+        # evaluator turns into observe=True on the decision) and
+        # audited, so the operator KNOWS the engine is wired up and
+        # watching, not enforcing. An operator can override
+        # default_on_empty to deny (fail-closed empty), warn (shadow),
+        # or allow (silent allow).
+        #
+        # SAFETY INVARIANT (the empty-vs-error boundary): this branch is
+        # reached ONLY when bundle resolution SUCCEEDED and produced
+        # zero rules. A resolution FAILURE (pull error, RLS/auth denial,
+        # decrypt failure) never reaches here -- it is caught upstream
+        # and routed to make_bundle_missing_policy(), which honors
+        # default_on_missing and STILL FAILS CLOSED (deny). So observe
+        # mode can never mask a resolution error as an allow.
         #
-        # Copy-choice note (2026-04-19, the 2026-04-19 P0): the previous
-        # message -- "No active policies. Define one in the Control Zero
-        # dashboard." -- presumed the user had not defined any policies.
-        # That presumption was wrong in the common case: the user had
-        # defined several, but the library-attachments state on the
-        # backend did not include any active attachment row, so the
-        # bundle arrived with zero policies while the dashboard Library
-        # tab still showed them. The new wording removes the
-        # presumption and points at the actual recovery action.
-        flat.append({
-            "effect": default_action,
-            "action": "*",
-            # T79: stamp a synthetic policy_id so the audit dashboard
-            # can render a recognizable chip + tooltip linking to the
-            # right troubleshooting anchor. The reason_code stays the
-            # same; the synthetic id is purely an audit-presentation
-            # contract (audit ingest stores it verbatim).
-            "id": "synthetic:NO_ACTIVE_POLICIES",
-            "reason": (
-                "No policies are active on this project. If the dashboard "
-                "shows attached policies, regenerate the policy bundle."
-            ),
-            "reason_code": "NO_ACTIVE_POLICIES",
-        })
+        # Copy-choice note (2026-04-19, the 2026-04-19 P0): the original
+        # NO_ACTIVE_POLICIES message presumed the user had defined no
+        # policies; in the common case the library-attachments state was
+        # simply empty while the dashboard still showed them. The wording
+        # below removes that presumption and points at recovery.
+        if default_on_empty == "observe":
+            # OBSERVE: allow + loud monitoring signal + audit.
+            flat.append({
+                "effect": "allow",
+                "action": "*",
+                "id": "synthetic:OBSERVE_MODE_NO_POLICY",
+                "reason": (
+                    "OBSERVE MODE: no policies are active on this project, so "
+                    "Control Zero is monitoring and auditing tool calls but "
+                    "NOT enforcing -- every call is allowed and logged. Attach "
+                    "a policy (or set the empty-project default to deny) in the "
+                    "Control Zero dashboard to start enforcing."
+                ),
+                "reason_code": "OBSERVE_MODE_NO_POLICY",
+            })
+        else:
+            # Explicit non-observe empty posture (deny / warn / allow).
+            # Keeps the historical NO_ACTIVE_POLICIES reason_code so
+            # dashboards still bucket it as "nothing attached". The
+            # effect honors the operator's declared default_on_empty.
+            flat.append({
+                "effect": default_on_empty,
+                "action": "*",
+                # T79: stamp a synthetic policy_id so the audit dashboard
+                # can render a recognizable chip + tooltip linking to the
+                # right troubleshooting anchor.
+                "id": "synthetic:NO_ACTIVE_POLICIES",
+                "reason": (
+                    "No policies are active on this project. If the dashboard "
+                    "shows attached policies, regenerate the policy bundle."
+                ),
+                "reason_code": "NO_ACTIVE_POLICIES",
+            })
 
     out = {
         "version": "1",
@@ -576,6 +621,7 @@ def translate_to_local_policy(payload: dict) -> dict:
         "settings": {
             "default_action": default_action,
             "default_on_missing": default_on_missing,
+            "default_on_empty": default_on_empty,
             "default_on_tamper": default_on_tamper,
         },
     }

{controlzero-1.9.2 → controlzero-1.9.4}/controlzero/_internal/enforcer.py

@@ -62,6 +62,20 @@ POLICY_ENGINE_VERSION = "0.1.0"
 REASON_CODE_RULE_MATCH = "RULE_MATCH"
 REASON_CODE_NO_RULE_MATCH = "NO_RULE_MATCH"
 REASON_CODE_NO_ACTIVE_POLICIES = "NO_ACTIVE_POLICIES"
+# OBSERVE_MODE_NO_POLICY (#1247 item 3 / #1252): a genuinely-empty,
+# rule-less bundle that RESOLVED SUCCESSFULLY (zero attached/active
+# policies) and whose resolved empty-policy posture is "observe". The
+# call is ALLOWED THROUGH but the decision is loudly flagged as
+# monitoring-only (observe=True on the decision) and audited, so the
+# operator knows the engine is NOT enforcing. This is deliberately a
+# DISTINCT code from NO_ACTIVE_POLICIES (which remains for the
+# deny/warn empty-posture cases and pre-refinement consumers) and from
+# BUNDLE_MISSING (a resolution FAILURE, which still fails closed -- see
+# make_bundle_missing_policy). The empty-vs-error boundary is the
+# security-critical invariant here: OBSERVE_MODE_NO_POLICY is ONLY ever
+# emitted on the SUCCESSFUL-resolution empty path, never on a pull /
+# RLS / auth error.
+REASON_CODE_OBSERVE_MODE_NO_POLICY = "OBSERVE_MODE_NO_POLICY"
 REASON_CODE_BUNDLE_MISSING = "BUNDLE_MISSING"
 REASON_CODE_BUNDLE_TAMPERED = "BUNDLE_TAMPERED"
 REASON_CODE_MACHINE_QUARANTINED = "MACHINE_QUARANTINED"
@@ -93,6 +107,7 @@ VALID_REASON_CODES = frozenset({
     REASON_CODE_RULE_MATCH,
     REASON_CODE_NO_RULE_MATCH,
     REASON_CODE_NO_ACTIVE_POLICIES,
+    REASON_CODE_OBSERVE_MODE_NO_POLICY,
     REASON_CODE_BUNDLE_MISSING,
     REASON_CODE_BUNDLE_TAMPERED,
     REASON_CODE_MACHINE_QUARANTINED,
@@ -129,6 +144,7 @@ VALID_REASON_CODES = frozenset({
 SYNTHETIC_POLICY_ID_PREFIX = "synthetic:"
 SYNTHETIC_NO_RULE_MATCH = "synthetic:NO_RULE_MATCH"
 SYNTHETIC_NO_ACTIVE_POLICIES = "synthetic:NO_ACTIVE_POLICIES"
+SYNTHETIC_OBSERVE_MODE_NO_POLICY = "synthetic:OBSERVE_MODE_NO_POLICY"
 SYNTHETIC_BUNDLE_MISSING = "synthetic:BUNDLE_MISSING"
 SYNTHETIC_RESOURCE_GATE_SKIP = "synthetic:RESOURCE_GATE_SKIP"
 SYNTHETIC_QUARANTINE = "synthetic:QUARANTINE"
@@ -137,6 +153,7 @@ SYNTHETIC_ENGINE_UNAVAILABLE = "synthetic:ENGINE_UNAVAILABLE"
 VALID_SYNTHETIC_POLICY_IDS = frozenset({
     SYNTHETIC_NO_RULE_MATCH,
     SYNTHETIC_NO_ACTIVE_POLICIES,
+    SYNTHETIC_OBSERVE_MODE_NO_POLICY,
     SYNTHETIC_BUNDLE_MISSING,
     SYNTHETIC_RESOURCE_GATE_SKIP,
     SYNTHETIC_QUARANTINE,
@@ -155,8 +172,30 @@ DEFAULT_BUNDLE_ACTION = "deny"
 DEFAULT_BUNDLE_ON_MISSING = "deny"
 DEFAULT_BUNDLE_ON_TAMPER = "warn"
 
+# default_on_empty (#1247 item 3 / #1252, founder-approved posture
+# refinement): the effect for a genuinely-EMPTY bundle -- one that
+# RESOLVED SUCCESSFULLY but has zero attached/active rules. This is a
+# SEPARATE knob from default_action (which governs the non-empty
+# no-match path). The distinction is the whole point: an org that has
+# authored an allow-list deliberately wants no-match -> deny
+# (default_action), while an org that has attached NOTHING YET should
+# not be bricked day-one -- it observes (allow + audit + a loud
+# "monitoring, not enforcing" signal) instead.
+#
+# Canonical default is "observe": a fresh/empty hosted project allows
+# tool calls through but loudly flags + audits every one as
+# OBSERVE_MODE_NO_POLICY, so the operator sees the engine is wired up
+# and watching, then authors real rules. An operator can override to
+# "deny" (fail-closed empty), "warn" (shadow), or "allow" (silent
+# allow, discouraged). CRITICAL: this only ever applies on the
+# SUCCESSFUL-resolution empty path; a resolution ERROR routes through
+# make_bundle_missing_policy + default_on_missing and STILL FAILS
+# CLOSED -- default_on_empty never weakens the error path.
+DEFAULT_BUNDLE_ON_EMPTY = "observe"
+
 VALID_DEFAULT_ACTIONS = frozenset({"deny", "allow", "warn"})
 VALID_DEFAULT_ON_MISSING = frozenset({"deny", "allow"})
+VALID_DEFAULT_ON_EMPTY = frozenset({"observe", "deny", "allow", "warn"})
 VALID_DEFAULT_ON_TAMPER = frozenset({"warn", "deny", "deny-all", "quarantine"})
 
 
@@ -217,6 +256,19 @@ class PolicyDecision:
     # requires_approval is True. None falls back to policy_id at
     # request time so the approver always sees a label.
     approval_action: Optional[str] = None
+    # observe (#1247 item 3 / #1252): True when this decision is an
+    # OBSERVE-MODE allow -- the call is permitted (effect="allow") but
+    # the engine is NOT enforcing because the bundle is genuinely empty
+    # (zero attached/active policies) and the resolved empty-policy
+    # posture is "observe". This is the LOUD signal the security review
+    # mandated: an observe allow must never look like a normal,
+    # rule-driven allow. Consumers (CLI output, audit annotation, hook
+    # banners) branch on this to print "OBSERVE MODE: monitoring, not
+    # enforcing". It is set ONLY alongside
+    # reason_code=OBSERVE_MODE_NO_POLICY and is False on every other
+    # path (including a real rule that happens to allow, and the
+    # fail-closed BUNDLE_MISSING / NO_RULE_MATCH paths).
+    observe: bool = False
 
     @property
     def decision(self) -> str:
@@ -457,6 +509,25 @@ class PolicyEvaluator:
                 reason_code=decision_code,
                 evaluated_rules=evaluated,
                 gate_matched=gate_matched_value,
+                # #1247 item 3: the empty-bundle observe catch-all
+                # (synthetic OBSERVE_MODE_NO_POLICY rule) is an allow
+                # that must be loudly flagged as monitoring-only. Set
+                # the observe signal here so CLI / hook / audit
+                # consumers can distinguish it from a normal
+                # rule-driven allow.
+                #
+                # Hardening (security review L1): gate on BOTH the
+                # reason_code AND the synthetic policy_id, so that even a
+                # (backend-signed) bundle rule that carried a forged
+                # reason_code="OBSERVE_MODE_NO_POLICY" cannot mislabel a
+                # rule-driven allow as observe -- the synthetic id is
+                # only ever stamped by translate_to_local_policy's empty
+                # branch. observe is an audit/UX label, never an
+                # authorization input, so this is belt-and-suspenders.
+                observe=(
+                    decision_code == REASON_CODE_OBSERVE_MODE_NO_POLICY
+                    and (rule.id or "") == SYNTHETIC_OBSERVE_MODE_NO_POLICY
+                ),
             )
             # DLP scan: only when the policy decision is "allow" and args exist
             if decision.allowed and args and self._dlp_scanner is not None:
@@ -475,11 +546,32 @@ class PolicyEvaluator:
         # that regex-match the reason string (a pattern we actively
         # discourage -- use reason_code instead) keep working.
         if self._default_action == "deny":
-            reason = "No matching policy rule (fail-closed default)"
+            # #1247 (folded from #1257): a deny-by-default no-rule-match is
+            # the single most confusing block a customer hits -- a benign
+            # tool (e.g. `bash:find`) is denied not because a rule forbids
+            # it but because no rule mentions it and the bundle's
+            # default_on_missing is deny. The historical message ("fail-
+            # closed default") gave no path out and looked like a bug.
+            # Name the unmatched action and the exact remediation so the
+            # deny is self-explaining. The leading phrase keeps the legacy
+            # "fail-closed default" substring for any downstream regex
+            # consumer (reason_code=NO_RULE_MATCH is the supported signal;
+            # this is belt-and-suspenders). NOTE: this is the NON-EMPTY
+            # bundle path -- a genuinely empty bundle short-circuits to the
+            # synthetic OBSERVE catch-all above and never reaches here, so
+            # observe and self-explaining-deny compose cleanly.
+            reason = (
+                f"No matching policy rule for '{action}' (fail-closed default; "
+                "default_on_missing=deny). This tool is neither allowed nor "
+                "denied by any rule in your hosted policy, so it is blocked. "
+                "Add a rule that allows it (e.g. allow: '*' as a catch-all, or "
+                f"allow: '{action}'), or set the project/org default to allow, "
+                "in the Control Zero dashboard."
+            )
         elif self._default_action == "allow":
-            reason = "No matching policy rule (default_action=allow)"
+            reason = f"No matching policy rule for '{action}' (default_action=allow)"
         else:  # "warn"
-            reason = "No matching policy rule (default_action=warn)"
+            reason = f"No matching policy rule for '{action}' (default_action=warn)"
 
         # T79: distinguish the T83-class signature ("a rule's actions
         # matched but its resources gate excluded the call") from the

{controlzero-1.9.2 → controlzero-1.9.4}/controlzero/cli/main.py

@@ -214,6 +214,18 @@ def test(tool: str, method: str, policy: str, args: str, hitl: Optional[str], hi
     click.echo(f"args:    {args_dict}")
     click.echo("")
     click.secho(f"DECISION: {decision.effect.upper()}", fg=color, bold=True)
+    # #1247 item 3: an observe-mode allow is NOT a normal allow -- the
+    # engine is monitoring, not enforcing, because the project has no
+    # active policies. Print a distinct, loud line so the operator can
+    # never mistake an empty-bundle observe for "my rules allowed this".
+    if getattr(decision, "observe", False):
+        click.secho(
+            "OBSERVE MODE: monitoring, not enforcing -- this project has "
+            "no active policies, so every tool call is allowed and logged. "
+            "Attach a policy to start enforcing.",
+            fg="yellow",
+            bold=True,
+        )
     if decision.policy_id:
         click.echo(f"matched: {decision.policy_id}")
     if decision.reason:

{controlzero-1.9.2 → 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.2 → 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.2 → 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):