chore(stack): merge the shared supervision refactor with main (#4701) into provider token resolvers

Signed-off-by: Drew Newberry <anewberry@nvidia.com>

Author: drew

.agents/skills/test-release-canary/SKILL.md

@@ -144,7 +144,7 @@ Loopback registration auto-derives the gateway name to `openshell` if `--name` i
 | Sandbox create or exec fails | Published sandbox and supervisor artifacts are missing, incompatible, or cannot establish the protected runtime channel. | Gateway logs plus Docker, Podman, VM, snap, or Kubernetes runtime diagnostics for the job. |
 | `macos`/`ubuntu-deb`/`fedora` job fails on `openshell status` | Local gateway service did not start (systemd/brew/podman). Often a driver issue. | Service logs in the job log; `OPENSHELL_COMPUTE_DRIVER` env in the "Ensure …" step. |
 | `ubuntu-snap-system-docker` fails during `install.sh` | System Docker was unavailable to the runner user, the edge revision or automatic interfaces were unavailable, or the user gateway did not become reachable. | Failure diagnostics dump system Docker, snap service/connection/change state, user and legacy gateway journals, snap logs, and port 17670 listeners. |
-| `ubuntu-snap-system-docker` fails during the prover checks | The prover artifact is missing or packaged for the wrong architecture, `openshell.prover` is not exposed or confined to read the test policies, or its solver linkage is not runnable. | The `Install and check status` and `Check a policy boundary with the snap prover` steps, plus `snap info openshell` and `snap connections openshell`. |
+| `ubuntu-snap-system-docker` fails during the prover checks | The prover artifact is missing or packaged for the wrong architecture, `openshell.prover` is not exposed, missing the alias to `openshell-prover`, or not permitted to read the test policies, or its solver linkage is not runnable. | The `Install and check status` and `Check a policy boundary with the snap prover` steps, plus `snap info openshell` and `snap connections openshell`. |
 | `ubuntu-snap-docker-preflight` unexpectedly succeeds | The installer no longer fails before installing the OpenShell snap when Docker is absent or supplied by the Docker snap. | Inspect `install.log`, `docker-snap.log`, `snap list`, and snapd changes. |
 | `kubernetes` job fails on `helm install --wait` | Chart did not deploy in 5 min — usually image pull failure or readiness probe failing. | "Diagnostics on failure" step dumps `helm status`, manifest, pod describe, pod logs. |
 | `kubernetes` job fails on `kubectl wait` | Gateway pod stuck `CrashLoopBackOff` or `ImagePullBackOff`. | Diagnostics dump; check `:dev` image existence at `ghcr.io/nvidia/openshell/gateway`. |

.github/workflows/branch-checks.yml

@@ -221,6 +221,7 @@ jobs:
           cargo fmt --manifest-path examples/governance-interceptor/Cargo.toml --all -- --check
           cargo fmt --manifest-path examples/supervisor-middleware-content-guard/Cargo.toml --all -- --check
           cargo fmt --manifest-path examples/isolation-backend-v8/Cargo.toml --all -- --check
+          cargo fmt --manifest-path tests/testkit/Cargo.toml --all -- --check
 
   cargo-lockfiles:
     name: Cargo lockfiles
@@ -277,6 +278,7 @@ jobs:
           cargo clippy --locked --manifest-path examples/governance-interceptor/Cargo.toml --all-targets -- -D warnings
           cargo clippy --locked --manifest-path examples/supervisor-middleware-content-guard/Cargo.toml --all-targets -- -D warnings
           cargo clippy --locked --manifest-path examples/isolation-backend-v8/Cargo.toml --all-targets -- -D warnings
+          cargo clippy --locked --manifest-path tests/testkit/Cargo.toml --all-targets -- -D warnings
 
   rust-test:
     name: Rust test (${{ matrix.system }})
@@ -325,6 +327,7 @@ jobs:
         run: |
           cargo nextest run --locked --profile ci --workspace --features openshell-server/test-support
           cargo nextest run --locked --config-file .config/nextest.toml --profile ci --manifest-path examples/supervisor-middleware-content-guard/Cargo.toml
+          cargo nextest run --locked --config-file .config/nextest.toml --profile ci --manifest-path tests/testkit/Cargo.toml
 
   rust-postgres-test:
     name: Rust PostgreSQL tests

.github/workflows/release-canary.yml

@@ -239,7 +239,7 @@ jobs:
           docker info
           sudo snap connections openshell | grep -E '^docker +openshell:docker +:docker +'
           openshell --version
-          openshell.prover --version
+          openshell-prover --version
           snap services openshell
           systemctl --user is-enabled --quiet snap.openshell.user-gateway.service
           systemctl --user is-active snap.openshell.user-gateway.service
@@ -283,7 +283,7 @@ jobs:
             read_only:
               - /usr
           EOF
-          result=$(openshell.prover check "$prover_dir/candidate.yaml" \
+          result=$(openshell-prover check "$prover_dir/candidate.yaml" \
             --boundary "$prover_dir/boundary.yaml")
           grep -q '^result: within_boundary$' <<<"$result"
 

AGENTS.md

@@ -54,7 +54,6 @@ Do not rely on this file for a full inventory. The detailed public and contribut
 | `crates/openshell-driver-mxc/` | Microsoft MXC compute driver | In-process Windows AppContainer and isolation-session compute backend |
 | `crates/openshell-prover/` | Policy prover | Policy verification and proof generation |
 | `crates/openshell-prover-cli/` | Policy prover CLI | Standalone local policy boundary checks |
-| `crates/openshell-server-macros/` | Server macros | Compile-time helpers for gateway RPC authorization |
 | `crates/openshell-supervisor-middleware/` | Middleware runtime | Generic middleware registry, remote service integration, and chain execution |
 | `crates/openshell-supervisor-middleware-builtins/` | Built-in middleware | First-party in-process middleware implementations |
 | `crates/openshell-supervisor-network/` | Network supervisor | Proxying, L7 enforcement, policy evaluation, and provider credential injection |
@@ -63,6 +62,7 @@ Do not rely on this file for a full inventory. The detailed public and contribut
 | `python/openshell/` | Python SDK | Python bindings and CLI packaging |
 | `sdk/typescript/` | TypeScript SDK | Native Connect client, curated sandbox API, and generated protobuf types |
 | `proto/` | Protobuf definitions | gRPC service contracts |
+| `tests/testkit/` | E2E testkit | Support library and `#[testkit::test]` attribute for SDK-driven E2E suites |
 | `deploy/` | Docker, Helm, K8s | Dockerfiles, Helm chart, manifests |
 | `docs/` | Published docs | MDX pages, navigation, and content assets |
 | `fern/` | Docs site config | Fern site config, components, and theme assets |

CONTRIBUTING.md

@@ -344,6 +344,7 @@ These are the primary `mise` tasks for day-to-day development:
 | `sdk/typescript/` | TypeScript SDK (Connect client and generated protobuf bindings) |
 | `proto/`        | Protocol buffer definitions and [public API conventions](proto/README.md) |
 | `tasks/`        | `mise` task definitions and build scripts     |
+| `tests/testkit/` | Support library for SDK-driven end-to-end suites |
 | `deploy/`       | Dockerfiles, Helm chart, Kubernetes manifests |
 | `docs/`         | Published Fern docs source, navigation, and content assets |
 | `fern/`         | Fern site config, components, and theme assets |

Cargo.lock

@@ -16,6 +16,7 @@ crates/*/tests/        # Rust integration tests
 python/openshell/      # Python unit tests (*_test.py suffix)
 e2e/python/            # Python E2E tests (test_*.py prefix)
 e2e/rust/              # Rust CLI E2E tests
+tests/testkit/         # Support library for SDK-driven E2E suites
 ```
 
 ## Rust Tests
@@ -129,6 +130,16 @@ requires mTLS.
 runtime. It covers the current schema and the Podman in-tree versus external
 driver configuration boundary.
 
+### testkit (`tests/testkit/`)
+
+`testkit` is the support library for SDK-driven end-to-end suites. Tests are
+`#[testkit::test]` functions with a required doc comment. They find the
+gateway the same way the CLI does, through `OPENSHELL_GATEWAY_ENDPOINT`,
+`OPENSHELL_GATEWAY`, or the active gateway, and `cx.cli` runs the CLI named
+by `OPENSHELL_BIN`. See
+[tests/testkit/README.md](tests/testkit/README.md) for how to write and run
+tests.
+
 ### Python E2E (`e2e/python/`)
 
 `mise run e2e:python` builds `openshell/e2e-python:dev` from
@@ -447,14 +458,19 @@ OPENSHELL_E2E_KUBE_TEST=smoke mise run e2e:kubernetes
 ```
 
 **OpenShift**: when the target cluster exposes the `route.openshift.io` API
-group, the harness automatically applies SCC-compatible Helm overrides, grants
-the required SCCs (`privileged` to `openshell-sandbox`, and `anyuid` to the
-PostgreSQL fixture for DB scenarios), and drives the gateway through a
-passthrough Route with mandatory mTLS instead of port-forward. No extra flags are
-needed, but `oc` must be installed and authenticated against the target cluster
-with permission to modify SCC bindings (`oc adm policy add-scc-to-user`) — the
-harness exits early if `oc` is missing. The SCC grants and extracted client
-mTLS material are removed during cleanup, including on failure or interrupt.
+group, the harness automatically applies SCC-compatible Helm overrides and
+drives the gateway through a passthrough Route with mandatory mTLS instead of
+port-forward. No extra flags are needed, but `oc` must be installed and
+authenticated against the target cluster; the harness exits early if `oc` is
+missing. DB scenarios grant `anyuid` to the PostgreSQL fixture and require
+permission to modify SCC bindings (`oc adm policy add-scc-to-user`). That grant
+and extracted client mTLS material are removed during cleanup, including on
+failure or interrupt.
+
+Sandbox pods use the namespace-assigned UID/GID and run under `restricted-v2`
+without a privileged SCC grant to `openshell-sandbox`. Earlier versions required
+that grant for in-container isolation setup. [RFC 0012](https://github.com/NVIDIA/OpenShell/blob/main/rfc/0012-isolation-backend/README.md#motivation)
+explains the isolation backend separation behind the capability-free runtime.
 
 On a **remote** cluster, drop the `e2e-host-gateway` feature. Those tests rely
 on the sandbox-side `host.openshell.internal` alias reaching the machine running

TESTING.md

@@ -54,8 +54,6 @@ hyper-util = { workspace = true }
 hyper-rustls = { version = "0.27", default-features = false, features = ["native-tokio", "http1", "http2", "tls12", "logging"] }
 rustls = { workspace = true }
 rustls-pemfile = { workspace = true }
-tokio-rustls = { workspace = true }
-tower = { workspace = true }
 reqwest = { workspace = true }
 
 # Error handling
@@ -71,9 +69,6 @@ tempfile = "3"
 oauth2 = { version = "5", default-features = false, features = ["reqwest"] }
 base64 = { workspace = true }
 
-# WebSocket (Cloudflare tunnel proxy)
-tokio-tungstenite = { workspace = true }
-
 # Streams
 futures = { workspace = true }
 tokio-stream = { workspace = true }

crates/openshell-cli/Cargo.toml

@@ -9,14 +9,10 @@ use openshell_bootstrap::edge_token::load_edge_token;
 use openshell_bootstrap::oidc_token::{is_token_expired, load_oidc_token, store_oidc_token};
 use openshell_bootstrap::{list_gateways, load_active_gateway, load_gateway_metadata};
 use openshell_core::ObjectName;
-use openshell_core::auth::EdgeAuthInterceptor;
-use openshell_core::proto::open_shell_client::OpenShellClient;
 use openshell_core::proto::{ListProvidersRequest, ListSandboxesRequest, ListWorkspacesRequest};
-use tonic::service::interceptor::InterceptedService;
-use tonic::transport::Channel;
 
 use crate::oidc_auth::oidc_refresh_token;
-use crate::tls::{TlsOptions, build_channel};
+use crate::tls::{GrpcClient, TlsOptions, grpc_client};
 
 /// Complete gateway names from local metadata files (no network call).
 pub fn complete_gateway_names(_prefix: &OsStr) -> Vec<CompletionCandidate> {
@@ -130,10 +126,7 @@ fn resolve_active_gateway() -> Option<(String, String)> {
     Some((metadata.gateway_endpoint, name))
 }
 
-async fn completion_grpc_client(
-    server: &str,
-    gateway_name: &str,
-) -> Option<OpenShellClient<InterceptedService<Channel, EdgeAuthInterceptor>>> {
+async fn completion_grpc_client(server: &str, gateway_name: &str) -> Option<GrpcClient> {
     let mut tls_opts = TlsOptions::default().with_gateway_name(gateway_name);
     tls_opts.gateway_insecure = std::env::var("OPENSHELL_GATEWAY_INSECURE")
         .is_ok_and(|v| !v.is_empty() && v != "0" && v != "false");
@@ -172,13 +165,7 @@ async fn completion_grpc_client(
         }
     }
 
-    let channel = build_channel(server, &tls_opts).await.ok()?;
-    let interceptor = EdgeAuthInterceptor::new(
-        tls_opts.oidc_token.as_deref(),
-        tls_opts.edge_token.as_deref(),
-    )
-    .ok()?;
-    Some(OpenShellClient::with_interceptor(channel, interceptor))
+    grpc_client(server, &tls_opts).await.ok()
 }
 
 /// Run an async future on a dedicated thread to avoid nested tokio runtime panics.