Skip to content

Commit 6ea9cd0

Browse files
authored
refactor(supervisor): move backend setup behind the selected backend (NVIDIA#4176)
* refactor(supervisor): move backend setup behind the selected backend Keep launch decoding, policy discovery and client construction with the trusted backend while sharing supervisor admission and lifecycle handling. Preserve VM policy identity validation and live credential handles. Exercise alternate launch data through shared startup, readiness and shutdown, including confirmation denial and resource cleanup. Closes NVIDIA#4173 Signed-off-by: Shiju <[email protected]> * fix(supervisor): resolve backend setup lint failures Box shared startup futures to keep callers' async state small. Use the private module boundary for backend setup visibility and keep test helpers and defaults explicit without changing their inputs. Signed-off-by: Shiju <[email protected]> * refactor(supervisor): simplify selected backend startup Signed-off-by: Shiju <[email protected]> * test(supervisor): keep imports before descriptor assertions Signed-off-by: Shiju <[email protected]> * test(supervisor): preserve discovery failure startup coverage Exercise backend discovery failure through shared startup before the existing confirmation denial and successful shutdown cases. Assert that startup preserves the error without launching a workload or readiness. Signed-off-by: Shiju <[email protected]> --------- Signed-off-by: Shiju <[email protected]>
1 parent ba76704 commit 6ea9cd0

4 files changed

Lines changed: 1232 additions & 59 deletions

File tree

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
# OpenShell supervisor
2+
3+
The supervisor loads and reconciles policy, maintains provider credentials, applies network and MCP inspection, and drives the admitted isolation backend through attachment, confirmation, and workload start.
4+
5+
## Backend startup
6+
7+
The public `run_sandbox` entry point selects the OpenShell Sandbox Protocol backend and collects its startup inputs into a private `SandboxRunConfig`. Shared startup receives that config and the trusted backend setup separately. The `backend_setup` module owns that backend's launch-data decoder, workload policy discovery, and client construction. Descriptor contents cannot select an implementation.
8+
9+
Shared startup checks the admitted backend name before passing the opaque payload to its decoder. It then compares the decoded sandbox, session, and runtime generation with the trusted launch inputs before installing credentials or discovering workload policy. A mismatch stops startup.
10+
11+
The built-in decoder also carries the VM driver's fixed workload identity into shared policy validation. Startup and later policy updates must reject selectors that conflict with that identity. Other launch descriptors do not enable this VM-specific check.
12+
13+
The supervisor admits policy and prepares credentials before constructing and attaching the selected client. It uses the isolation contract's `BoundBoundary` and `ConfirmedBoundary` directly: confirm the attached boundary, prepare network mediation, then start the workload. Backend implementations remain responsible for validating their native enforcement evidence through the isolation contract.
14+
15+
The client receives the supervisor's live provider state, bearer-token slot, and CA-path slot. Provider refresh, token rotation, and later CA publication must remain visible through those shared handles. Startup does not create independent copies of their current values.
16+
17+
The setup interface stays private to the supervisor. It adds no runtime backend registration, endpoint configuration, or public factory API. The public `run_sandbox` signature and standard backend selection remain unchanged.
Lines changed: 250 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,250 @@
1+
// SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
2+
// SPDX-License-Identifier: Apache-2.0
3+
4+
//! Backend-owned launch decoding and client construction for supervisor startup.
5+
6+
use std::path::PathBuf;
7+
use std::sync::{Arc, Mutex};
8+
9+
use miette::Result;
10+
use openshell_core::SandboxSessionId;
11+
use openshell_core::jwt::{SessionBearerTokenSlot, SupervisorAuthBundle};
12+
use openshell_core::provider_credentials::ProviderCredentialState;
13+
use openshell_isolation_interface::AgentSpec;
14+
use openshell_isolation_interface::contract::{
15+
BackendDescriptor, BackendError, BackendRegistry, BoundBoundary, IsolationBackend,
16+
ResolvedWorkloadIdentity, SandboxContext, SandboxPolicy,
17+
};
18+
19+
/// Coordinates decoded by the selected trusted backend. Shared startup checks
20+
/// these against admission before credentials or discovery reach that backend.
21+
pub struct LaunchIdentity {
22+
pub sandbox_id: String,
23+
pub generation: String,
24+
pub session_id: SandboxSessionId,
25+
pub workload_identity: ResolvedWorkloadIdentity,
26+
/// Preserve driver-fixed VM selectors during shared startup and reload.
27+
pub vm_policy_identity: Option<super::VmPolicyIdentity>,
28+
}
29+
30+
/// Runtime state remains owned by the supervisor. Backends retain these same
31+
/// handles so CA publication, provider reload, and bearer rotation stay visible
32+
/// after attachment; copying their current contents would lose later updates.
33+
pub struct BackendServices {
34+
pub ca_file_paths: Arc<Mutex<Option<(PathBuf, PathBuf)>>>,
35+
pub provider_credentials: ProviderCredentialState,
36+
pub sandbox_bearer: SessionBearerTokenSlot,
37+
}
38+
39+
/// Selected by trusted composition, never by payload contents. Decoding and
40+
/// construction may prepare a client but must not launch workload code.
41+
pub trait BackendSetup: Sync {
42+
/// Name chosen by trusted composition and checked against admission before decoding.
43+
fn backend_name(&self) -> &str;
44+
45+
/// Decode native launch data without starting workload code. The returned
46+
/// identity must describe the same resource retained by the prepared backend.
47+
fn decode(
48+
&self,
49+
payload: &[u8],
50+
) -> std::result::Result<(LaunchIdentity, Box<dyn PreparedBackend>), BackendError>;
51+
}
52+
53+
/// Native launch data stays with its backend until client construction. Shared
54+
/// startup admits policy and credentials between discovery and attachment.
55+
#[tonic::async_trait]
56+
pub trait PreparedBackend: Send + Sync {
57+
/// Read image policy through the backend's authenticated client. An invalid
58+
/// or unreadable policy must return the invalid flag or an error, never missing.
59+
async fn discover_policy(
60+
&self,
61+
bearer: SessionBearerTokenSlot,
62+
) -> std::result::Result<(Option<String>, bool), BackendError>;
63+
64+
/// Consume prepared launch data and retain the supervisor's live handles.
65+
/// Construction does not attach the resource or start workload code.
66+
fn build(
67+
self: Box<Self>,
68+
services: BackendServices,
69+
) -> std::result::Result<Arc<dyn IsolationBackend>, BackendError>;
70+
}
71+
72+
/// Created only after name and launch identity checks. Consuming attachment
73+
/// prevents reusing one prepared startup to build or attach a second client.
74+
pub struct SelectedBackend {
75+
descriptor: BackendDescriptor,
76+
identity: LaunchIdentity,
77+
prepared: Box<dyn PreparedBackend>,
78+
}
79+
80+
impl SelectedBackend {
81+
/// Reject absent or mismatched admission before decoding, then bind the
82+
/// decoded sandbox, session, and generation to trusted launch inputs.
83+
pub fn select(
84+
setup: &dyn BackendSetup,
85+
descriptor: BackendDescriptor,
86+
admitted_backend: Option<&str>,
87+
sandbox_id: Option<&str>,
88+
auth: &SupervisorAuthBundle,
89+
) -> Result<Self> {
90+
let admitted_backend = admitted_backend.ok_or_else(|| {
91+
miette::miette!("runtime descriptor supplied without an admitted isolation backend")
92+
})?;
93+
if descriptor.backend_name != admitted_backend {
94+
return Err(miette::miette!(
95+
"descriptor backend {:?} does not match admitted backend {admitted_backend:?}",
96+
descriptor.backend_name
97+
));
98+
}
99+
if setup.backend_name() != admitted_backend {
100+
return Err(miette::miette!(
101+
"selected backend {:?} does not match admitted backend {admitted_backend:?}",
102+
setup.backend_name()
103+
));
104+
}
105+
106+
let (identity, prepared) = setup
107+
.decode(&descriptor.payload)
108+
.map_err(|error| miette::miette!(error.to_string()))?;
109+
if sandbox_id.is_none_or(|id| id.is_empty() || identity.sandbox_id != id) {
110+
return Err(miette::miette!(
111+
"runtime descriptor does not match admitted sandbox"
112+
));
113+
}
114+
if identity.session_id != auth.session_id {
115+
return Err(miette::miette!(
116+
"supervisor authentication bundle does not match runtime session"
117+
));
118+
}
119+
if identity.generation != auth.runtime_generation.as_str() {
120+
return Err(miette::miette!(
121+
"supervisor authentication bundle does not match runtime generation"
122+
));
123+
}
124+
Ok(Self {
125+
descriptor,
126+
identity,
127+
prepared,
128+
})
129+
}
130+
131+
/// Return the backend name already matched to the admitted selection.
132+
pub fn backend_name(&self) -> &str {
133+
&self.descriptor.backend_name
134+
}
135+
136+
/// Carry the selected backend's VM identity constraint into policy handling.
137+
pub fn vm_policy_identity(&self) -> Option<super::VmPolicyIdentity> {
138+
self.identity.vm_policy_identity
139+
}
140+
141+
/// Delegate image discovery only after shared name and identity checks.
142+
/// Callers may retry this read; discovery cannot authorize workload launch.
143+
pub async fn discover_policy(
144+
&self,
145+
bearer: SessionBearerTokenSlot,
146+
) -> Result<(Option<String>, bool)> {
147+
self.prepared
148+
.discover_policy(bearer)
149+
.await
150+
.map_err(|error| miette::miette!("discover workload image policy: {error}"))
151+
}
152+
153+
/// Construct and attach the selected client using the admitted policy and
154+
/// shared services. Registry verification rejects a differently named client.
155+
pub async fn attach(
156+
self,
157+
services: BackendServices,
158+
policy: SandboxPolicy,
159+
agent: AgentSpec,
160+
) -> Result<Box<dyn BoundBoundary>> {
161+
let backend = self
162+
.prepared
163+
.build(services)
164+
.map_err(|error| miette::miette!(error.to_string()))?;
165+
let mut registry = BackendRegistry::new();
166+
registry
167+
.register(backend)
168+
.map_err(|error| miette::miette!(error.to_string()))?;
169+
let admitted_backend = self.descriptor.backend_name.clone();
170+
let (backend, verified) = registry
171+
.resolve(self.descriptor, &admitted_backend)
172+
.map_err(|error| miette::miette!(error.to_string()))?;
173+
backend
174+
.attach(
175+
verified,
176+
SandboxContext {
177+
sandbox_id: self.identity.sandbox_id,
178+
session_id: self.identity.session_id,
179+
policy,
180+
agent,
181+
identity: self.identity.workload_identity,
182+
},
183+
)
184+
.await
185+
.map_err(|error| miette::miette!(error.to_string()))
186+
}
187+
}
188+
189+
/// The standard binary selects the `OpenShell` Sandbox Protocol. Its wire schema
190+
/// and concrete client stay here rather than in the shared startup sequence.
191+
pub struct OpenShellBackendSetup;
192+
193+
impl BackendSetup for OpenShellBackendSetup {
194+
fn backend_name(&self) -> &str {
195+
openshell_sandbox_backend::BACKEND_NAME
196+
}
197+
198+
fn decode(
199+
&self,
200+
payload: &[u8],
201+
) -> std::result::Result<(LaunchIdentity, Box<dyn PreparedBackend>), BackendError> {
202+
let descriptor: openshell_sandbox_backend::boundary_protocol::SandboxRuntimeDescriptor =
203+
serde_json::from_slice(payload).map_err(|error| {
204+
BackendError::Descriptor(format!("decode sandbox runtime descriptor: {error}"))
205+
})?;
206+
let identity = LaunchIdentity {
207+
sandbox_id: descriptor.boundary_id.clone(),
208+
generation: descriptor.generation.clone(),
209+
session_id: descriptor.session_id,
210+
workload_identity: descriptor.workload_identity.clone(),
211+
vm_policy_identity: descriptor
212+
.resource_claims
213+
.contains_key("vm.generation")
214+
.then_some(super::VmPolicyIdentity {
215+
uid: descriptor.workload_identity.uid,
216+
gid: descriptor.workload_identity.gid,
217+
}),
218+
};
219+
Ok((identity, Box::new(OpenShellLaunch(descriptor))))
220+
}
221+
}
222+
223+
struct OpenShellLaunch(openshell_sandbox_backend::boundary_protocol::SandboxRuntimeDescriptor);
224+
225+
#[tonic::async_trait]
226+
impl PreparedBackend for OpenShellLaunch {
227+
async fn discover_policy(
228+
&self,
229+
bearer: SessionBearerTokenSlot,
230+
) -> std::result::Result<(Option<String>, bool), BackendError> {
231+
openshell_sandbox_backend::OpenShellRuntimeBackend::discover_policy(self.0.clone(), bearer)
232+
.await
233+
}
234+
235+
fn build(
236+
self: Box<Self>,
237+
services: BackendServices,
238+
) -> std::result::Result<Arc<dyn IsolationBackend>, BackendError> {
239+
Ok(Arc::new(
240+
openshell_sandbox_backend::OpenShellRuntimeBackend::new(
241+
services.ca_file_paths,
242+
services.provider_credentials,
243+
services.sandbox_bearer,
244+
),
245+
))
246+
}
247+
}
248+
249+
#[cfg(test)]
250+
mod tests;

0 commit comments

Comments
 (0)