|
| 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