feat(api)!: use sandbox names as canonical references

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

Author: drew

.agents/skills/tui-development/SKILL.md

@@ -479,12 +479,13 @@ use openshell_core::proto::{
 
 ### Proto field gotchas
 
-- `DeleteSandboxRequest` uses the `name` field (not `id`):
+- `DeleteSandboxRequest` uses the canonical sandbox name and an explicit workspace:
   ```rust
   let req = openshell_core::proto::DeleteSandboxRequest {
-      name: sandbox_name,
-      workspace_scope: Some(workspace_selector(workspace)),
+      sandbox: sandbox_name,
+      workspace: workspace.to_string(),
       allow_missing: true,
+      ..Default::default()
   };
   ```
 - Delete responses carry `DeletionOutcome`: distinguish `Accepted` (cleanup
@@ -493,21 +494,23 @@ use openshell_core::proto::{
 - `WatchSandboxRequest` has extra fields beyond what you might need — always use `..Default::default()`:
   ```rust
   let req = openshell_core::proto::WatchSandboxRequest {
-      id: sandbox_id,
+      sandbox: sandbox_name,
       follow_status: false,
       follow_logs: true,
       follow_events: false,
       log_tail_lines: 0,
+      workspace: workspace.to_string(),
       ..Default::default()
   };
   ```
 - `SandboxLogLine` proto fields: `sandbox_id`, `event_time` (`Option<prost_types::Timestamp>`), `level`, `target`, `message`, `source`, `fields` (`HashMap<String, String>`).
-- Workspace-scoped request fields use `workspace_scope: Option<WorkspaceSelector>`.
-  Select one workspace with `Some(workspace_selector(name))`. List requests that
-  explicitly support cross-workspace access also accept
-  `Some(all_workspaces_selector())`; do not use that marker on other requests.
-- `GetSandboxLogsRequest` fields: `sandbox_id`, `lines` (u32), `since_time` (`Option<prost_types::Timestamp>`),
-  `sources` (Vec<String>), `min_level` (String), `workspace_scope`.
+- Single-resource requests use a `workspace: String` field with the canonical
+  workspace name. Collection list requests use
+  `workspace_scope: Option<WorkspaceSelector>` so callers can select one
+  workspace with `Some(workspace_selector(name))` or, where authorized,
+  `Some(all_workspaces_selector())`.
+- `GetSandboxLogsRequest` fields: `sandbox`, `lines` (u32), `since_time` (`Option<prost_types::Timestamp>`),
+  `sources` (Vec<String>), `min_level` (String), `workspace`.
 - `ListSandboxesRequest` fields: `page_size` (i32), `page_token` (String),
   `label_selector` (String), `workspace_scope`.
 - `ListProvidersRequest` fields: `page_size` (i32), `page_token` (String),
@@ -517,12 +520,12 @@ use openshell_core::proto::{
 - Paginated list responses return `next_page_token`. Continue with the same
   request parameters and that token until it is empty; changing filters or
   scope invalidates the token.
-- `UpdateConfigRequest` fields include `name` (String, sandbox name or empty for
-  global), `setting_key`, `setting_value`, `delete_setting` (bool), `global`
-  (bool), and `workspace_scope`. Sandbox-scoped updates require a named selector;
-  gateway-global updates must leave `workspace_scope` as `None`.
-- Most resource requests require an explicit named `workspace_scope`, including
-  the `default` workspace. An omitted selector is not an implicit default.
+- `UpdateConfigRequest` fields include `sandbox` (String, canonical sandbox name),
+  `setting_key`, `setting_value`, `delete_setting` (bool), `global` (bool), and
+  `workspace`. Sandbox-scoped updates require canonical `sandbox` and `workspace`
+  names; gateway-global updates leave both fields empty.
+- Most single-resource requests require an explicit canonical `workspace` name,
+  including the `default` workspace. An empty value is not an implicit default.
 
 ### gRPC timeouts
 

architecture/gateway.md

@@ -110,13 +110,20 @@ cross-origin or sibling-subdomain request.
 
 Public workspace-scoped RPCs carry a typed `WorkspaceSelector`. A request must
 select one non-empty workspace explicitly; `default` is an ordinary explicit
-name, not an omitted-value fallback. Sandbox, sandbox template, provider, and
-service list RPCs also accept an all-workspaces marker after Platform Admin
-authorization. Single-workspace handlers reject that marker. Platform-global
-policy operations require the selector to be absent, while workspace policy
-operations require it. The gateway authorizes the selected scope before
-performing resource lookup so malformed, unsupported, and unauthorized scopes
-have consistent behavior across resource types.
+name, not an omitted-value fallback. Every public sandbox-scoped RPC identifies
+the sandbox with a string `sandbox` and carries its canonical workspace name in
+a separate string `workspace` field. Canonical sandbox IDs remain internal metadata used
+at authentication, persistence, and compute-driver boundaries; public callers
+do not use them as sandbox references. The gateway resolves the name to the
+persisted sandbox record only after authorizing the selected workspace. A
+sandbox principal is instead resolved by the immutable ID in its authenticated
+identity, then checked against the requested name and workspace. Missing and
+unauthorized references use the same response within each principal class so
+the resolver does not expose an object-existence oracle. Sandbox, sandbox
+template, provider, and service collection list RPCs use `workspace_scope` so
+they can also accept an all-workspaces marker after Platform Admin
+authorization. Platform-global policy operations require `sandbox` and
+`workspace` to be empty, while sandbox policy operations require both.
 
 Docker and Podman report the local address through which their sandboxes can
 reach the gateway. When the primary listener covers that address, the gateway
@@ -793,8 +800,8 @@ channel and returns the exec with an error. Once a command reports its exit
 status, the gateway also bounds how long it waits for the trailing channel close.
 
 `ForwardTcp` is the client-facing byte stream for SSH and service forwarding.
-The first frame is a `TcpForwardInit` that carries the sandbox ID, an
-authorization token from `CreateSshSession`, and an explicit target:
+The first frame is a `TcpForwardInit` that carries the workspace-scoped sandbox
+name, an authorization token from `CreateSshSession`, and an explicit target:
 `target.ssh` for the sandbox SSH socket or `target.tcp` for a loopback service
 inside the sandbox. The gateway validates the token and sandbox readiness,
 sends a targeted `RelayOpen` to the supervisor, then bridges

crates/openshell-cli/src/commands/provider.rs

@@ -64,8 +64,8 @@ pub async fn sandbox_provider_list(
     let mut client = grpc_client(server, tls).await?;
     let response = client
         .list_sandbox_providers(ListSandboxProvidersRequest {
-            sandbox_name: name.to_string(),
-            workspace_scope: Some(openshell_core::proto::workspace_selector(workspace)),
+            sandbox: (name).to_string(),
+            workspace: (workspace).to_string(),
         })
         .await
         .into_diagnostic()?;
@@ -96,8 +96,8 @@ pub async fn sandbox_provider_attach(
     // Fetch current sandbox to get resource_version for CAS
     let sandbox = client
         .get_sandbox(GetSandboxRequest {
-            name: name.to_string(),
-            workspace_scope: Some(openshell_core::proto::workspace_selector(workspace)),
+            sandbox: (name).to_string(),
+            workspace: (workspace).to_string(),
         })
         .await
         .into_diagnostic()?
@@ -110,10 +110,10 @@ pub async fn sandbox_provider_attach(
     let response = match client
         .attach_sandbox_provider(AttachSandboxProviderRequest {
             request_id: String::new(),
-            sandbox_name: name.to_string(),
+            sandbox: (name).to_string(),
+            workspace: (workspace).to_string(),
             provider_name: provider.to_string(),
             expected_resource_version: resource_version,
-            workspace_scope: Some(openshell_core::proto::workspace_selector(workspace)),
         })
         .await
     {
@@ -153,8 +153,8 @@ pub async fn sandbox_provider_detach(
     // Fetch current sandbox to get resource_version for CAS
     let sandbox = client
         .get_sandbox(GetSandboxRequest {
-            name: name.to_string(),
-            workspace_scope: Some(openshell_core::proto::workspace_selector(workspace)),
+            sandbox: (name).to_string(),
+            workspace: (workspace).to_string(),
         })
         .await
         .into_diagnostic()?
@@ -167,10 +167,10 @@ pub async fn sandbox_provider_detach(
     let response = match client
         .detach_sandbox_provider(DetachSandboxProviderRequest {
             request_id: String::new(),
-            sandbox_name: name.to_string(),
+            sandbox: (name).to_string(),
+            workspace: (workspace).to_string(),
             provider_name: provider.to_string(),
             expected_resource_version: resource_version,
-            workspace_scope: Some(openshell_core::proto::workspace_selector(workspace)),
         })
         .await
     {
@@ -498,7 +498,7 @@ async fn auto_create_provider(
                 profile_workspace: workspace.to_string(),
                 credential_handles: HashMap::new(),
             }),
-            workspace_scope: Some(openshell_core::proto::workspace_selector(workspace)),
+            workspace: (workspace).to_string(),
         };
 
         let response = client.create_provider(request).await.map_err(|status| {
@@ -547,7 +547,7 @@ async fn auto_create_provider(
                     profile_workspace: workspace.to_string(),
                     credential_handles: HashMap::new(),
                 }),
-                workspace_scope: Some(openshell_core::proto::workspace_selector(workspace)),
+                workspace: (workspace).to_string(),
             };
 
             match client.create_provider(request).await {
@@ -683,7 +683,7 @@ async fn rollback_provider_create_after_gcloud_adc_failure(
             request_id: String::new(),
             allow_missing: true,
             name: provider_name.to_string(),
-            workspace_scope: Some(openshell_core::proto::workspace_selector(workspace)),
+            workspace: (workspace).to_string(),
         })
         .await
     {
@@ -1138,7 +1138,7 @@ pub async fn provider_create_with_options(options: ProviderCreateOptions<'_>) ->
                 profile_workspace: profile_workspace.to_string(),
                 credential_handles: HashMap::new(),
             }),
-            workspace_scope: Some(openshell_core::proto::workspace_selector(workspace)),
+            workspace: (workspace).to_string(),
         })
         .await
         .into_diagnostic()?;
@@ -1169,7 +1169,7 @@ pub async fn provider_create_with_options(options: ProviderCreateOptions<'_>) ->
                     "refresh_token".to_string(),
                 ],
                 expiration_time: None,
-                workspace_scope: Some(openshell_core::proto::workspace_selector(workspace)),
+                workspace: (workspace).to_string(),
             })
             .await
         {
@@ -1188,7 +1188,7 @@ pub async fn provider_create_with_options(options: ProviderCreateOptions<'_>) ->
                 request_id: String::new(),
                 provider: provider_name.clone(),
                 credential_key: adc_credential_key,
-                workspace_scope: Some(openshell_core::proto::workspace_selector(workspace)),
+                workspace: (workspace).to_string(),
             })
             .await
         {
@@ -1229,7 +1229,7 @@ pub async fn provider_get(
     let response = client
         .get_provider(GetProviderRequest {
             name: name.to_string(),
-            workspace_scope: Some(openshell_core::proto::workspace_selector(workspace)),
+            workspace: (workspace).to_string(),
         })
         .await
         .into_diagnostic()?;
@@ -1762,7 +1762,7 @@ pub async fn provider_refresh_status(
         .get_provider_refresh_status(GetProviderRefreshStatusRequest {
             provider: name.to_string(),
             credential_key: credential_key.unwrap_or_default().to_string(),
-            workspace_scope: Some(openshell_core::proto::workspace_selector(workspace)),
+            workspace: (workspace).to_string(),
         })
         .await
         .into_diagnostic()?
@@ -1848,7 +1848,7 @@ pub async fn provider_refresh_config(
                 .map(openshell_core::time::timestamp_from_millis)
                 .transpose()
                 .into_diagnostic()?,
-            workspace_scope: Some(openshell_core::proto::workspace_selector(workspace)),
+            workspace: (workspace).to_string(),
         })
         .await
         .into_diagnostic()?
@@ -1878,7 +1878,7 @@ pub async fn provider_rotate(
             request_id: String::new(),
             provider: name.to_string(),
             credential_key: credential_key.to_string(),
-            workspace_scope: Some(openshell_core::proto::workspace_selector(workspace)),
+            workspace: (workspace).to_string(),
         })
         .await
         .into_diagnostic()?
@@ -1917,7 +1917,7 @@ pub async fn provider_refresh_delete(
             allow_missing: true,
             provider: name.to_string(),
             credential_key: credential_key.to_string(),
-            workspace_scope: Some(openshell_core::proto::workspace_selector(workspace)),
+            workspace: (workspace).to_string(),
         })
         .await
         .into_diagnostic()?
@@ -2288,7 +2288,7 @@ pub async fn provider_update(options: ProviderUpdateOptions<'_>) -> Result<()> {
     let existing = match client
         .get_provider(GetProviderRequest {
             name: name.to_string(),
-            workspace_scope: Some(openshell_core::proto::workspace_selector(workspace)),
+            workspace: (workspace).to_string(),
         })
         .await
     {
@@ -2384,7 +2384,7 @@ pub async fn provider_update(options: ProviderUpdateOptions<'_>) -> Result<()> {
                 })
                 .collect::<Result<HashMap<_, _>, _>>()
                 .into_diagnostic()?,
-            workspace_scope: Some(openshell_core::proto::workspace_selector(workspace)),
+            workspace: (workspace).to_string(),
             clear_credential_expiration_keys,
         })
         .await
@@ -2417,7 +2417,7 @@ pub async fn provider_delete(
                 request_id: String::new(),
                 allow_missing: true,
                 name: name.clone(),
-                workspace_scope: Some(openshell_core::proto::workspace_selector(workspace)),
+                workspace: (workspace).to_string(),
             })
             .await
         {