docs(cpex): align demo + docs with MCP-frame authorization-error rendering

After merging PR #501 (shared MCP rejection renderer, httpx/render.go), cpex
denials on the HTTP proxies render as an MCP JSON-RPC 2.0 error frame at HTTP 200
for classified MCP requests (code -32000, error.data.error=cpex.<code>), and fall
back to plain 403/502 only for non-MCP requests. The demo and docs still
described the old transport-level 403. Truth them up:

- Chat agent (agent.py): format_tool_response reads the cpex code from
  error.data.error (was error.data.violation, which the renderer never emits).
  Verified live in-container against a real deny frame. Fix a stale '-> 403'
  comment.
- Scenarios 02/05/06/07/08/09: headers + notes now expect HTTP 200 + JSON-RPC
  error frame (error.data.error=cpex.*), not HTTP 403. Re-ran all 9: deny frames
  match.
- README: taint S3 line now says denied via MCP JSON-RPC error frame.
- CHAT-WALKTHROUGH.md: fix all four deny sections (code -32001 -> -32000,
  data.violation -> data.error with the real cpex codes).
- Plugin docs (plugins/cpex/README.md, docs/cpex-plugin.md): the deny/error
  wire shape is now described as listener-dependent (MCP frame at 200 vs plain
  403/502). Also correct the stale 'body modifications aren't re-serialized'
  limitation: re-serialization is implemented; the real limitation is that
  multi-part rewrites fail closed.

Signed-off-by: Frederico Araujo <frederico.araujo@ibm.com>

Author: araujof

authbridge/authlib/plugins/cpex/README.md

@@ -233,7 +233,7 @@ taint all run inside cpex via its own sub-plugins, so the AuthBridge-side
 | `hooks.on_response` | empty | CPEX hooks fired during OnResponse, in order |
 | `config` | empty | CPEX runtime YAML inline; mutually exclusive with `config_file` |
 | `config_file` | empty | path to CPEX YAML; mounted from a ConfigMap in production |
-| `fail_open` | `false` | on a CPEX internal error: deny with 502 (false) or continue (true) |
+| `fail_open` | `false` | on a CPEX internal error: deny (false) or continue (true). The rejection renders per the listener — MCP error frame for MCP requests, else HTTP 502 (see Decisions and denials) |
 | `worker_threads` | `0` | CPEX tokio worker pool size; 0 lets CPEX pick |
 | `bypass_paths` | health + `.well-known` | URL path globs that skip CPEX entirely |
 | `bypass_hosts` | keycloak / SPIRE / observability | host globs that skip CPEX, outbound only |
@@ -256,19 +256,41 @@ The plugin maps the CPEX outcome onto AuthBridge's five-value invocation
 vocabulary:
 
 - **allow**: all sub-plugins continued, request proceeds untouched.
-- **deny**: a sub-plugin returned a policy violation. Rejects with HTTP 403 and a
-  `cpex.<code>` violation code (`cpex.pii_detected`,
-  `cpex.session_tainted_secret`, and so on).
+- **deny**: a sub-plugin returned a policy violation with a `cpex.<code>` code
+  (`cpex.pii_detected`, `cpex.session_tainted_secret`, and so on). The plugin
+  emits a `Reject`; how it appears on the wire is the listener's call, not the
+  plugin's (see below).
 - **modify**: policy rewrote the body, headers, or labels. Changes are applied,
   the request continues.
 - **observe**: audit-only outcome, recorded, request continues.
 
+**How a rejection is rendered.** The plugin sets the decision and a status
+(`403` for a policy deny, `502` for a CPEX-internal error); the HTTP/proxy
+listeners then choose the wire shape (`authbridge/authlib/listener/httpx/render.go`):
+
+- **Classified MCP request** (an MCP parser populated the MCP extension with a
+  JSON-RPC `method` and `id`) → an **MCP JSON-RPC 2.0 error frame at HTTP 200**,
+  with the original id echoed back:
+  `{"jsonrpc":"2.0","id":<id>,"error":{"code":-32000,"message":<reason>,"data":{"error":"cpex.<code>","plugin":"cpex"}}}`.
+  The caller's MCP client surfaces this as a failed tool call rather than a
+  transport break. This covers both a policy deny and a fail-closed internal
+  error — they differ in the frame's `message` / `data.error`, not the HTTP
+  status.
+- **Everything else** (non-MCP requests, or JSON-RPC notifications with no id) →
+  a plain HTTP response carrying the status the plugin set: **403 Forbidden** for
+  a policy deny, **502 Bad Gateway** for a CPEX-internal error, with a
+  `{"error":"cpex.<code>",...}` body.
+
+(The gRPC listeners — extproc / extauthz — don't use this renderer and surface
+denials per their own protocol.)
+
 A CPEX policy `deny` is a normal outcome and is always honored. `fail_open` only
 governs CPEX-internal failures (an FFI error, an unreachable backend, a
-modification that cannot be applied). With `fail_open: false` those reject with
-HTTP 502; with `true` they log and continue. The default is fail-closed because a
-CPEX error usually means a misconfigured policy or an unreachable PDP, and
-silently allowing traffic in that state is rarely intended.
+modification that cannot be applied): with `fail_open: false` those are rejected
+(rendered as above — an MCP error frame for MCP requests, otherwise HTTP 502);
+with `true` they log and continue. The default is fail-closed because a CPEX
+error usually means a misconfigured policy or an unreachable PDP, and silently
+allowing traffic in that state is rarely intended.
 
 ## Building and testing
 

authbridge/demos/hr-cpex/README.md

@@ -129,7 +129,7 @@ content, which is what distinguishes it from scenario 07's content-based
 PII deny. Scenario 08 shows all three beats with fresh per-run session
 ids: a clean session sends fine (S1 → 200), reading compensation taints
 a second session (S2 → 200), and that session can no longer send email
-(S3 → 403 `cpex.session_tainted_secret`).
+(S3 → denied with an MCP JSON-RPC error frame, `cpex.session_tainted_secret`).
 
 **Act 5 — cross-principal taint isolation (scenario 09).** Session taint
 is keyed by the authenticated subject, not the raw `X-Session-Id`: the

authbridge/demos/hr-cpex/agent/CHAT-WALKTHROUGH.md

@@ -76,8 +76,8 @@ Alice: look up the compensation for EMP-001234
 
 **Expected:**
 - LLM invokes `get_compensation(employee_id="EMP-001234")`
-- Gateway response: **HTTP 200 + JSON-RPC error envelope**, code `-32001`,
-  `data.violation = "routes.tool:get_compensation.apl.policy[0]"`
+- Gateway response: **HTTP 200 + JSON-RPC error envelope**, code `-32000`,
+  `data.error = "cpex.routes_tool_get_compensation_apl_policy_0_"`
 - LLM apologizes politely without revealing the violation code
   (system prompt tells it to do exactly this)
 
@@ -171,8 +171,8 @@ short-circuited at the PDP.)
 
 **Expected:**
 - LLM invokes `search_repos(repo_name="partner-sdk", visibility="external")`
-- Gateway response: **HTTP 200 + JSON-RPC error envelope**, code `-32001`,
-  `data.violation = "cedar.default_deny"`
+- Gateway response: **HTTP 200 + JSON-RPC error envelope**, code `-32000`,
+  `data.error = "cpex.cedar_default_deny"`
 - LLM apologizes
 
 **Under the hood:**
@@ -198,8 +198,8 @@ Bob: search the engineering repos for anything
 
 **Expected:**
 - LLM invokes `search_repos(visibility="internal")` (or similar)
-- Gateway response: **HTTP 200 + JSON-RPC error envelope**, code `-32001`,
-  `data.violation = "routes.tool:search_repos.apl.policy[0]"`
+- Gateway response: **HTTP 200 + JSON-RPC error envelope**, code `-32000`,
+  `data.error = "cpex.routes_tool_search_repos_apl_policy_0_"`
 - LLM apologizes
 
 **Talking point:** the APL gate denied at the cheapest layer — Bob is
@@ -220,8 +220,8 @@ Bob: send an email to alice@corp.com with the subject "FYI"
 
 **Expected:**
 - LLM invokes `send_email(to="alice@corp.com", subject="FYI", body="Jane's SSN is 555-12-3456 if you need it")`
-- Gateway response: **HTTP 200 + JSON-RPC error envelope**, code `-32001`,
-  `data.violation = "pii.detected"`
+- Gateway response: **HTTP 200 + JSON-RPC error envelope**, code `-32000`,
+  `data.error = "cpex.pii_detected"`
 - LLM apologizes
 
 **Under the hood:**

authbridge/demos/hr-cpex/agent/agent.py

@@ -161,7 +161,7 @@
                     # result.ssn for callers without view_ssn. An `ssn` echo-back
                     # arg used to live here, but models populate it
                     # inconsistently (""/null/omitted) and a null value trips the
-                    # APL redact(args.ssn) type check (expected Str) → 403. The
+                    # APL redact(args.ssn) type check (expected Str) → deny. The
                     # request-side args.ssn redaction is still exercised by the
                     # deterministic curl matrix (scenarios/01-bob-allow.sh).
                 },
@@ -269,11 +269,15 @@ def format_tool_response(status: int, data: dict[str, Any]) -> str:
     if status >= 400:
         return json.dumps({"gateway_status": status, "error": data})
     if "error" in data:
+        # MCP JSON-RPC 2.0 error frame (HTTP 200). The forward proxy renders
+        # cpex denials this way for MCP requests; the violation code lives at
+        # error.data.error (see authbridge/authlib/listener/httpx/render.go),
+        # NOT error.data.violation.
         err = data["error"]
         return json.dumps(
             {
                 "error": err.get("message", "tool error"),
-                "violation": (err.get("data") or {}).get("violation"),
+                "violation": (err.get("data") or {}).get("error"),
             }
         )
     result = data.get("result", {})

authbridge/demos/hr-cpex/scenarios/02-alice-deny.sh

@@ -1,10 +1,11 @@
 #!/usr/bin/env bash
 # Alice (engineer, role.engineer) calls get_compensation. Expected:
 #
-#   * Gateway returns HTTP 403 with a JSON error body
-#     {"error":"cpex.<sanitized-code>",...,"plugin":"cpex"}. A CPEX
-#     policy deny is an authorization decision, surfaced by AuthBridge
-#     as a transport-level 403 (not a 500, not an MCP JSON-RPC envelope)
+#   * Gateway denies with an MCP JSON-RPC 2.0 error frame at HTTP 200:
+#     error.message = the human reason, error.data.error = the cpex code
+#     (cpex.<sanitized-code>), error.data.plugin = cpex. The forward proxy
+#     renders MCP-protocol errors for MCP requests (see
+#     authbridge/authlib/listener/httpx/render.go).
 #   * No token exchange happened (Keycloak's /token endpoint
 #     should NOT receive a token-exchange call for this request)
 #   * MCP server NEVER sees the call (request short-circuits at policy)
@@ -13,7 +14,7 @@ set -euo pipefail
 source "$(dirname "$0")/_lib.sh"
 
 step "Alice (engineer) → get_compensation"
-note "Expected: HTTP 403, code=cpex.routes_tool_get_compensation_apl_policy_0_"
+note "Expected: HTTP 200 + JSON-RPC error frame, error.data.error=cpex.routes_tool_get_compensation_apl_policy_0_"
 note "Triggered by: require(role.hr) deny BEFORE delegation runs"
 note "Expected upstream: no inbound request (gateway short-circuited)"
 

authbridge/demos/hr-cpex/scenarios/05-alice-external-cedar-deny.sh

@@ -10,15 +10,16 @@
 #   Layers 3-4 — never reached. No token exchange. GitHub never sees
 #             the request.
 #
-# Result: HTTP 403 with JSON error body, code = cpex.cedar_default_deny
-# — a CPEX policy deny is surfaced by AuthBridge as a transport-level
-# 403 (not a 500, not an MCP JSON-RPC envelope).
+# Result: HTTP 200 with an MCP JSON-RPC 2.0 error frame,
+# error.data.error = cpex.cedar_default_deny (the forward proxy renders
+# MCP-protocol errors for MCP requests; see
+# authbridge/authlib/listener/httpx/render.go).
 
 set -euo pipefail
 source "$(dirname "$0")/_lib.sh"
 
 step "Alice (engineering) → search_repos(visibility='external')"
-note "Expected: HTTP 403, code=cpex.cedar_default_deny"
+note "Expected: HTTP 200 + JSON-RPC error frame, error.data.error=cpex.cedar_default_deny"
 note "Triggered by: Cedar denies — engineering can't read external repos"
 note "Expected upstream: no inbound request (gateway short-circuits at PDP)"
 

authbridge/demos/hr-cpex/scenarios/06-bob-apl-deny.sh

@@ -12,14 +12,15 @@
 #   Layers 2-4 — never reached. Cedar never invoked, IdP never
 #             called, no token-exchange round-trip.
 #
-# Result: HTTP 403 with JSON error body, code = the cpex.* form of the
-# apl.policy step index that failed (cpex.routes_tool_search_repos_apl_policy_0_).
+# Result: HTTP 200 with an MCP JSON-RPC 2.0 error frame; error.data.error =
+# the cpex.* form of the apl.policy step index that failed
+# (cpex.routes_tool_search_repos_apl_policy_0_).
 
 set -euo pipefail
 source "$(dirname "$0")/_lib.sh"
 
 step "Bob (HR) → search_repos (gateway short-circuits at the APL gate)"
-note "Expected: HTTP 403, code=cpex.routes_tool_search_repos_apl_policy_0_"
+note "Expected: HTTP 200 + JSON-RPC error frame, error.data.error=cpex.routes_tool_search_repos_apl_policy_0_"
 note "Triggered by: require(team.engineering | team.security) — Bob is team.hr"
 note "Expected: Cedar never runs; IdP never called"
 

authbridge/demos/hr-cpex/scenarios/07-bob-pii-deny.sh

@@ -12,9 +12,9 @@
 # its observation record for the deny, so operators see the event.
 #
 # Expected:
-#   * HTTP 403 with JSON error body, code = cpex.pii_detected — a CPEX
-#     policy deny is surfaced by AuthBridge as a transport-level 403
-#     (not a 500, not an MCP JSON-RPC envelope)
+#   * HTTP 200 with an MCP JSON-RPC 2.0 error frame, error.data.error =
+#     cpex.pii_detected (the forward proxy renders MCP-protocol errors for
+#     MCP requests; see authbridge/authlib/listener/httpx/render.go)
 #   * Backend (hr-mcp) NEVER receives the call — the deny is
 #     enforced at the gateway plugin layer
 #   * stderr (from the gateway process) shows a JSON audit record
@@ -24,7 +24,7 @@ set -euo pipefail
 source "$(dirname "$0")/_lib.sh"
 
 step "Bob (HR + email_send) → send_email with SSN in body"
-note "Expected: HTTP 403, code=cpex.pii_detected"
+note "Expected: HTTP 200 + JSON-RPC error frame, error.data.error=cpex.pii_detected"
 note "Triggered by: pii-scan plugin catches the SSN pattern in args"
 note "Expected: audit-log still emits a record describing the deny"
 note "Expected upstream: no inbound request (gateway plugin denied)"

authbridge/demos/hr-cpex/scenarios/08-bob-taint-deny.sh

@@ -18,7 +18,7 @@
 # Three steps:
 #   S1  clean session, clean body          → 200  (baseline: email works)
 #   S2  new session, get_compensation      → 200  (taints session "secret")
-#   S3  SAME session as S2, clean body     → 403  cpex.session_tainted_secret
+#   S3  SAME session as S2, clean body     → 200 + JSON-RPC error frame, cpex.session_tainted_secret
 #
 # Watch the gateway with:  kubectl -n cpex-demo logs -f deploy/hr-cpex-agent -c authbridge-cpex
 
@@ -44,7 +44,7 @@ SESSION_ID="$SID_TAINT" call_get_compensation "$BOB" "$CLIENT" true
 
 step "S3 · Bob → send_email (SAME session as S2, clean body)"
 note "Session: $SID_TAINT (now carries label \"secret\" from S2)"
-note "Expected: HTTP 403, code=cpex.session_tainted_secret"
+note "Expected: HTTP 200 + JSON-RPC error frame, error.data.error=cpex.session_tainted_secret"
 note "Denied by the session taint — NOT by pii-scan (the body has no PII)"
 note "This is the cross-tool data-flow control: looked at secrets → can't email out"
 SESSION_ID="$SID_TAINT" call_send_email "$BOB" "$CLIENT" "$CLEAN_BODY"

authbridge/demos/hr-cpex/scenarios/09-cross-principal-taint-isolation.sh

@@ -28,7 +28,7 @@
 #
 # Contrast with scenario 08, where bob reusing his OWN tainted session
 # is denied (cpex.session_tainted_secret). Same id, different subject =
-# different outcome. Pre-fix, S3 would have returned 403.
+# different outcome. Pre-fix, S3 would have been denied.
 #
 # Watch the gateway with:  kubectl -n cpex-demo logs -f deploy/hr-cpex-agent -c authbridge-cpex
 
@@ -57,5 +57,5 @@ step "S3 · Bob → send_email, SAME session id as eve used, clean body"
 note "Session: $SID_SHARED  (same string — but bound to bob's subject now)"
 note "Expected: 200 OK — bob's key H(bob:$SID_SHARED) != eve's H(eve:$SID_SHARED),"
 note "so bob does NOT inherit eve's \"secret\" taint. THIS is the Finding 2 fix."
-note "Pre-fix (raw session key) this would have been 403 cpex.session_tainted_secret."
+note "Pre-fix (raw session key) this would have been denied (cpex.session_tainted_secret)."
 SESSION_ID="$SID_SHARED" call_send_email "$BOB" "$CLIENT" "$CLEAN_BODY"