refactor(auth): separate sandbox identity from TLS

[drew]

Summary

Separate sandbox identity from transport security. Sandboxes now authenticate the gateway with its CA certificate and authenticate their own RPCs with the bearer-token bootstrap contract landed in #2968, so no user client certificate or private key is exposed inside a sandbox.

Gateway mTLS user authentication remains configurable through [openshell.gateway.mtls_auth] and no longer depends on the selected compute driver. This keeps the driver-free gateway free of first-party driver policy and addresses the authentication concern raised during review of #2823.

Related Issue

Related to #2417.

Follow-up to #2968; addresses review feedback from #2823.

Changes

• require only guest_tls_ca for sandbox-to-gateway TLS across Docker, Podman, Kubernetes, and VM drivers
• stop mounting, projecting, staging, or exporting gateway client certificates and private keys into sandboxes
• use sandbox JWTs as the sandbox identity at the gRPC authorization boundary
• make optional client-certificate verification and mTLS user authentication gateway-owned behavior independent of compute-driver selection
• retain explicit validation errors for obsolete driver cert/key settings instead of silently continuing to expose those credentials
• update architecture, gateway configuration, authentication, security, deployment, driver, RFC, e2e, and operational-skill documentation

Testing

• mise run pre-commit passes
• Unit tests added/updated
• E2E tests added/updated

Additional verification:

• cargo check -p openshell-core -p openshell-server -p openshell-driver-docker -p openshell-driver-podman -p openshell-driver-kubernetes -p openshell-driver-vm --all-targets
• full library tests for openshell-server, openshell-sandbox, and the Docker, Podman, Kubernetes, and VM compute drivers
• mise run e2e:docker
• mise run ci (Rust and other completed lanes passed; the Go lane encountered three pre-existing gateway-list tests that enumerate the host's installed /etc/openshell/gateways/default in addition to isolated test fixtures)

Checklist

• Follows Conventional Commits
• Commits are signed off (DCO)
• Architecture docs updated
• Public gateway and compute-driver docs updated

[github-actions]

🌿 Preview your docs: https://nvidia-preview-pr-3110.docs.buildwithfern.com/openshell

[github-actions]

This pull request has had no activity for 14 days and is now marked stale. It may be closed in 7 days if there is no further activity.

[drew]

gator-agent

PR Review Status

The identity separation is project-valid and the initial review found one blocking upgrade-cleanup regression in the Podman path. The existing branch checks are green, but required E2E dispatch waits until review feedback is resolved.

Action required: @drew, preserve best-effort deletion of the retired Podman certificate and key secrets and add upgrade-cleanup coverage.

Blocking findings:

• GATOR-3d7786a5-01: Podman sandbox deletion no longer removes legacy client certificate and private-key secrets.

Carried findings:

• None

Gator metadata

• Validation: Maintainer-authored follow-up to #2968 and #2823 implementing the authentication boundary described in the PR
• Docs: Fern, architecture, deployment, driver, RFC, and operational documentation updated
• Checks: Existing current-head branch, Helm, Trivy, DCO, and docs checks are green; required E2E has not been dispatched
• E2E: test:e2e is required for gateway authentication, sandbox lifecycle, and multi-driver changes, but dispatch waits for review resolution
• Head SHA: 3d7786a580bc6722df377690a1ab6e30d81e84c5
• Base SHA: 29e89a2f2289ad538c195e136baaaac2a92a3a2e
• Merge base SHA: 29e89a2f2289ad538c195e136baaaac2a92a3a2e
• Patch ID: 049652b44807b3c907c3c85644791e396439bbea
• Gator payload: 10
• Review mode: initial
• Previous reviewed SHA: none
• Review budget exhausted: no
• Maintainer decision required: no
• Next state: gator:in-review

[drew]

gator-agent

Warning — GATOR-3d7786a5-01 · Preserve cleanup of retired Podman TLS secrets

Summary: After an operator upgrades a TLS-enabled Podman gateway, deleting a sandbox created by the prior release now removes only its CA secret. The retired client certificate and private-key secrets remain in Podman indefinitely, preserving long-lived user credentials beyond the sandbox lifecycle and leaving a credential-escalation path if the secret store is later exposed.

Fix: Separate creation names from cleanup names: create and mount only the CA, but best-effort delete the legacy openshell-tls-cert- and openshell-tls-key- names too. Add an upgrade-cleanup regression test.

Verify: Seed the CA, certificate, and key secret names as a prior release would, delete the sandbox with this head, and confirm all three remove_secret calls occur and no legacy secret remains.

Agent context

• Ownership: This PR narrows the helper used by both normal and already-missing-container deletion paths from three names to one.
• Location: crates/openshell-driver-podman/src/container.rs:177
• Sibling paths: crates/openshell-driver-podman/src/driver.rs:1386, crates/openshell-driver-podman/src/driver.rs:1428