fix(proxy): include OPA deny reason in CONNECT 403 response

[zanetworker]

Summary

When a CONNECT request is denied by OPA policy, the 403 response used a generic "not permitted by policy" message for both "endpoint not in policy" and "endpoint matched but binary didn't match." Users had no way to distinguish the two without reading supervisor logs, making binary identity the #1 debugging friction when setting up agents.

Related Issue

Fixes #2355

Changes

• Added build_json_error_response_with_reason function that includes an optional reason field in the JSON body
• Updated the CONNECT deny response to forward the OPA deny_reason (which already contains detailed binary mismatch info)
• Empty reason is omitted for backward compatibility

Before:

{"detail":"CONNECT host:443 not permitted by policy","error":"policy_denied"}

After (binary mismatch):

{"detail":"CONNECT host:443 not permitted by policy","error":"policy_denied","reason":"binary '/usr/bin/python3.11' not allowed in policy 'allow_xxx' (ancestors: [...])"}

Testing

Bug reproduced live against a running sandbox:

# python3 is not in the aiplatform binary allowlist
openshell sandbox exec --name my-sandbox -- python3 -c "..."
# Current response: 403 with no reason (confirmed)
# After fix: 403 with reason field showing binary mismatch

• mise run pre-commit passes
• Unit tests added: policy_deny_response_includes_reason, policy_deny_response_omits_empty_reason
• Bug reproduced live against local Docker sandbox

Checklist

• Follows Conventional Commits
• Commits are signed off (DCO)
• Architecture docs updated (not applicable — response format addition only)

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[johntmyers]

gator-agent

PR Review Status

Validation: This PR is project-valid because it is a small, concentrated proxy bug fix linked to #2355 and addresses a user-visible sandbox policy debugging gap.
Head SHA: e333f14edf9e928e4ff1c5d408dcf1f9bf82c8dc

Review findings:

• Blocking: this changes the user-visible CONNECT denial JSON shape, and docs/observability/logging.mdx currently documents the denied CONNECT body with only error and detail. Please update that page to include the optional reason field and explain that it carries the OPA deny reason when available.
• Non-blocking: the independent code review found the implementation correct, but suggested adding an end-to-end-ish CONNECT policy-denial test that exercises handle_tcp_connection and asserts a non-empty OPA deny reason reaches the wire response, instead of only testing the response helper.

Docs: missing for a direct sandbox/proxy behavior change documented in docs/observability/logging.mdx.

Next state: gator:in-review

[johntmyers]

/ok to test e333f14

[github-actions]

Label test:e2e applied for e333f14. Open Branch E2E Checks, find the run for commit e333f14, and click Re-run all jobs to execute with the label set. The run will execute the standard E2E suite after building the required gateway and supervisor images once. The matching required CI gate status on this PR will flip green automatically once the run finishes.

[johntmyers]

gator-agent

PR Review Status

Validation: This PR is project-valid because it is a small, concentrated proxy bug fix linked to #2355 and addresses a user-visible sandbox policy debugging gap.
Head SHA: 785d231546ad98fee9ef0e92424c7263191bc84a

Review findings:

• No blocking findings remain. The previous docs blocker is resolved by the docs/observability/logging.mdx update.
• Non-blocking: the independent review still suggests adding an integration-style CONNECT policy-denial regression test that exercises the proxy path and asserts a non-empty OPA deny reason reaches the wire response, rather than only testing the response helper.

Docs: updated for the direct sandbox/proxy behavior change; no navigation update is needed for this existing docs page.

Next state: gator:watch-pipeline

[johntmyers]

/ok to test 785d231

[johntmyers]

gator-agent

Monitoring Complete

Monitoring is complete because this PR has merged.

Final status: latest gator state was gator:watch-pipeline; review feedback was resolved, test:e2e was applied, maintainer approval was present, and the PR merged at head 785d231546ad98fee9ef0e92424c7263191bc84a.

I removed the active gator:* label because there is nothing left for gator to monitor on this PR.