Why

Two intertwined problems were causing the security gateway to silently fail to protect agents:

1. Block responses were unreadable to LLM agents. The proxy returned 403 with a tiny JSON body. Most agent fetch code only checks response.ok and discards 4xx bodies, so the agent saw a generic network error and bailed. No information about why the page was blocked, or what to do about it.

2. The non-MITM forward-proxy path delivered silent broken protection. It returned 400 to every CONNECT, so all HTTPS traffic bypassed inspection entirely. In 2026 that's the entire web. The path was dead weight in practice but the default in code (mitm_enabled = false), and we just spent an hour debugging which mode each host was in. The install script already provisions and trusts a CA automatically — the "lower barrier to entry" rationale for keeping non-MITM has expired.

What changes

Block response shape (commit 509e596)

mitm_blocked_response now returns:

• HTTP/1.1 200 OK (so response.ok is true and the body reaches the LLM)
• Content-Type: text/html; charset=utf-8
• X-Calciforge-Blocked: true and X-Calciforge-Reason: <text> headers for tooling that wants structured signals without parsing HTML
• An HTML body the model can read: title, reason, "what this means", suggested next steps (look elsewhere, ask operator to allowlist, don't try to bypass)

The reason header is sanitised to ASCII so non-printable / multi-byte content can't break HTTP framing. Call sites that previously passed the literal string "Request rejected" now pass actual error context (decode failure detail, URL-substitution failure cause, header/body substitution failure cause).

MITM is the only proxy mode (commit e03e036)

• Deleted the entire axum forward-proxy implementation: proxy.rs::{intercept, proxy_handler, blocked_response, health_handler}, all of router.rs (build_app, vault_handler, VAULT_TOKEN_ENV).
• mitm.rs is now the single entry point. It already had its own health_response and vault_response; vault_json_response was inlined as a private helper.
• main.rs no longer branches on mitm_enabled. config.rs no longer has the field.
• Tests covering the old axum path were either deleted (when redundant with the MITM-mode coverage) or migrated to tests/mitm_https.rs (destination-allowlist block, ref-in-unsupported-content-type block, vault 401, vault 503).
• Bug fixed during the port: the MITM path's URL/header/body substitution-failure branches were echoing the resolver/allowlist error text into the block-response body — and that text contains the literal secret name. The new https_mitm_destination_allowlist_blocks_disallowed_host test asserts the body must not echo the ref name, and caught the leak. These call sites now use a generic block message and log the detail at warn! server-side.

CA auto-provisioning

If SECURITY_PROXY_CA_CERT / SECURITY_PROXY_CA_KEY are not set, the binary now generates a persistent self-signed CA at /var/lib/calciforge/ca.{pem,key} on first start (key file 0600). Subsequent starts load the existing CA. Verified working on Librarian (231): on first start after deploy, the CA was created and the proxy came up cleanly.

The install script's existing CA flow is unaffected — it pre-provisions before the binary starts, so the auto-fallback is for ad-hoc / dev usage where the binary runs standalone.

Stats

Migration notes

• Operators upgrading: SECURITY_PROXY_MITM_ENABLED=false in old systemd Environment= lines is silently ignored — there is no non-MITM mode anymore. The install script already defaulted MITM on, so most installs converge automatically. Old hosts that were sitting on stale config (e.g. Librarian 231, where the dropin pre-dated PR Automate managed OpenClaw local install #107) need a re-run of bash scripts/install.sh to pick up the new systemd units and OpenClaw drop-in.
• Plain HTTP still works through the proxy — hudsucker handles direct HTTP requests through the same pipeline as TLS-intercepted ones. One mode, one audit trail.
• Clients without CA trust get TLS errors on HTTPS as expected. Run the install script on the target host to install the Calciforge CA in its trust store.

Verified locally

$ systemctl restart calciforge-security-proxy
$ ls /var/lib/calciforge
ca.key  ca.pem                    # auto-generated CA, key 0600
$ curl -i -x http://127.0.0.1:18888 -X POST -H "X-Api-Key: {{secret:nope}}" http://example.com/api
HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
X-Calciforge-Blocked: true
X-Calciforge-Reason: Request rejected
...
<h1>Page blocked by Calciforge security gateway</h1>

🤖 Generated with Claude Code