feat(docker): support custom CA bundles for corporate forward proxies

Start with crates/openshell-core/src/config.rs and compare the existing proxy-ca handling in crates/openshell-driver-podman, then inspect crates/openshell-driver-docker/src/lib.rs. Check e2e/rust/Cargo.toml and tasks/scripts/gateway-docker.sh for Docker coverage and gateway inputs. Done means validated operator-owned CA configuration, Docker corporate-proxy e2e coverage, gateway support, and the four listed documentation updates.

User Story

As a platform operator running OpenShell with the Docker compute driver, I want to configure a corporate proxy CA bundle, so that Docker sandboxes can use private-CA HTTPS proxies and TLS-intercepting proxies with the same trust behavior as Podman and MicroVM sandboxes.

Problem Statement

Docker has partial corporate forward-proxy support. [openshell.drivers.docker] currently accepts:

• https_proxy
• no_proxy
• proxy_auth_file
• proxy_auth_allow_insecure
• proxy_connect_by_hostname

The driver validates these settings, stages proxy credentials for the companion supervisor, and passes the corresponding --upstream-proxy* arguments. This supports http:// proxies and https:// proxies whose certificates already chain to a trust root available to the supervisor.

Unlike the Podman and MicroVM drivers, Docker does not support proxy_ca_bundle. Operators therefore cannot supply the private CA needed to verify an HTTPS proxy or certificates re-signed by a TLS-intercepting corporate proxy. Docker also lacks a dedicated corporate-proxy end-to-end test comparable to podman_corporate_proxy.rs, vm_corporate_proxy.rs, and kubernetes_corporate_proxy.rs.

PR #2814 introduced Docker's current proxy configuration, and the Docker work folded into PR #2942 through PR #2965 preserved it in the companion-supervisor architecture. PR #3090 subsequently added the complete CA-bundle and e2e contract for the MicroVM driver. Docker should provide the same externally observable behavior.

Impact / Why This Matters

Corporate networks commonly use a private CA for the proxy endpoint, TLS interception of tunneled destinations, or both. In those environments, a Docker sandbox can have a policy that permits the destination and still fail during TLS setup because the Docker driver cannot deliver the operator's corporate CA to the supervisor and workload trust bundle.

Current workarounds are insufficient:

• Using a plain HTTP proxy may violate corporate requirements and does not establish trust for intercepted destination certificates.
• Installing the CA in every sandbox image duplicates deployment-owned trust configuration, allows images to drift, and does not configure the supervisor's own HTTPS connection to the proxy.
• Adding the CA to the Docker host or gateway does not guarantee that the supervisor container and sandbox workload receive it.
• Switching to Podman or MicroVM changes the deployment and isolation model solely to obtain a proxy capability already implemented in shared supervisor code.

The missing Docker e2e coverage also allows CONNECT routing, authentication, NO_PROXY, trust propagation, and fail-closed behavior to regress without detection in the Docker CI lane.

Proposed Design

Extend [openshell.drivers.docker] with an operator-owned proxy_ca_bundle path, matching the behavior already exposed by Podman and MicroVM:

[openshell.drivers.docker]
https_proxy = "https://proxy.corp.example:8443"
proxy_auth_file = "/etc/openshell/secrets/proxy-auth"
proxy_ca_bundle = "/etc/openshell/tls/proxy-ca.pem"

When configured, Docker sandboxes should trust the supplied bundle for both:

1. The TLS connection from the supervisor to an https:// proxy.
2. Upstream and workload certificates re-signed by a TLS-intercepting proxy.

The setting must remain part of the operator-owned driver configuration. Sandbox environment variables, image contents, and template.driver_config.docker must not be able to select, replace, or disable it. The configured host path should be validated before use, while the companion supervisor should receive only a driver-controlled container path.

Invalid or incoherent configuration must fail closed. A missing, unreadable, empty, oversized, or certificate-free bundle, or a bundle configured without https_proxy, must produce an actionable error rather than falling back to direct egress or default trust.

Add Docker corporate-proxy e2e coverage to the Docker CI lane. The test should exercise CONNECT routing, policy denial, NO_PROXY, proxy authentication, an HTTPS proxy with a private CA, intercepted destination TLS, and fail-closed validation. Update the Docker gateway task to accept OPENSHELL_SANDBOX_PROXY_CA_BUNDLE, consistent with the Podman task.

Acceptance Criteria

• [openshell.drivers.docker] accepts proxy_ca_bundle alongside the existing proxy fields.
• proxy_ca_bundle is an operator-owned gateway-host path and cannot be supplied or overridden through sandbox environment, image contents, or template.driver_config.docker.
• An https:// proxy using a private CA works when that CA is supplied in proxy_ca_bundle.
• Certificates re-signed by a TLS-intercepting proxy are trusted by both the supervisor's upstream connection and processes in the Docker workload container.
• The driver validates the bundle before use and rejects a missing, unreadable, empty, oversized, malformed, or certificate-free file.
• proxy_ca_bundle without https_proxy is rejected, and invalid proxy configuration never degrades to direct egress.
• The driver supplies a fixed container path to --upstream-proxy-ca-bundle; the gateway-host path is not exposed to the workload.
• Existing support for http:// and https:// proxy URLs, NO_PROXY, authentication, insecure-auth acknowledgement, and hostname CONNECT remains unchanged.
• A Docker corporate-proxy e2e test covers CONNECT routing, policy denial, NO_PROXY, authentication, HTTPS proxy CA trust, TLS interception, and fail-closed configuration.
• OPENSHELL_SANDBOX_PROXY_CA_BUNDLE is supported by the local Docker gateway task.
• docs/reference/gateway-config.mdx, docs/reference/sandbox-compute-drivers.mdx, crates/openshell-driver-docker/README.md, and architecture/sandbox.md document Docker's complete corporate-proxy behavior.

Alternatives Considered

Rely on the supervisor container's default trust store. This works only for proxies using public or preinstalled roots. It does not support deployment-specific private corporate CAs.

Install the corporate CA in each sandbox image. This duplicates operator configuration across images, can drift, and does not configure trust for the supervisor's connection to an HTTPS proxy.

Use only an http:// proxy. This sends proxy authentication in cleartext when credentials are configured and still does not solve TLS interception of destination traffic.

Expose CA configuration through workload environment or per-sandbox driver configuration. This would let sandbox-controlled input alter an operator security boundary and would be inconsistent with the existing proxy design.

Require Podman or MicroVM for private-CA proxies. Proxy trust should not force operators to change compute drivers when the shared supervisor already implements the required behavior.

Agent Investigation

Findings from main at 24706c175:

• crates/openshell-driver-docker/src/lib.rs flattens UpstreamProxyConfig into DockerComputeConfig, validates the existing fields, stages proxy_auth_file in driver-owned supervisor storage, and passes the existing --upstream-proxy* arguments to the companion supervisor.
• crates/openshell-core/src/config.rs defines the shared UpstreamProxyConfig used by Docker, but it has no proxy_ca_bundle field.
• crates/openshell-driver-podman supports proxy_ca_bundle, validates the file, projects it into the supervisor, and passes --upstream-proxy-ca-bundle.
• The MicroVM implementation from PR #3090 stages the bundle at a driver-controlled guest path and includes HTTPS-proxy and CA-trust e2e coverage.
• e2e/rust/Cargo.toml registers dedicated corporate-proxy tests for Podman, MicroVM, and Kubernetes, but not Docker.
• tasks/scripts/gateway-docker.sh forwards the existing proxy inputs but not OPENSHELL_SANDBOX_PROXY_CA_BUNDLE; gateway-podman.sh supports that variable.

Checklist

• I've reviewed existing issues and the architecture docs
• This is a design proposal, not a "please build this" request