fix(server): restrict sandbox principal RPC access

Author: TaylorMutch

architecture/gateway.md

@@ -53,6 +53,14 @@ token through `IssueSandboxToken`. Supervisors renew gateway JWTs in memory
 before expiry. Older tokens are not server-revoked; deployments bound replay
 exposure with short `gateway_jwt.ttl_secs` lifetimes.
 
+Sandbox JWTs are not user credentials. The gRPC router accepts
+`Principal::Sandbox` only on the supervisor-to-gateway RPC allowlist
+(`ConnectSupervisor`, `RelayStream`, token renewal, config sync, policy status,
+log push, and policy-analysis callbacks). Handlers then compare the
+authenticated sandbox ID with any sandbox ID or name resolved from the request.
+Supervisor control and relay streams require a matching sandbox principal before
+the gateway registers the session or bridges relay bytes.
+
 ## API Surface
 
 The gateway API is organized around platform objects and operational streams:

crates/openshell-server/src/auth/authenticator.rs

@@ -19,7 +19,7 @@
 //! - [`super::oidc::OidcAuthenticator`] — user OIDC Bearer tokens
 //! - [`PermissiveUserAuthenticator`] — final-fallback dev-mode catch-all
 //!   that produces a synthetic user principal when no OIDC is
-//!   configured. Preserves the pre-PR-1 "no OIDC = open" posture for
+//!   configured. Preserves the "no OIDC = open" dev posture for
 //!   singleplayer / helm-dev deployments.
 
 use super::identity::{Identity, IdentityProvider};
@@ -99,9 +99,9 @@ impl std::fmt::Debug for AuthenticatorChain {
 /// Final-fallback authenticator that produces a synthetic user principal
 /// for any request the earlier authenticators didn't claim. Used only
 /// when no user-side authentication is configured (no OIDC, no fronting
-/// proxy contract) — the pre-PR-1 gateway accepted such requests with
-/// no auth at all; this preserves that posture in a principal-aware
-/// way so handlers always see *some* principal in extensions.
+/// proxy contract). This preserves the dev-mode open posture in a
+/// principal-aware way so handlers always see *some* principal in
+/// extensions.
 ///
 /// Producing a User principal (rather than Anonymous) means dev-mode
 /// requests pass the per-handler IDOR guard via the User-bypass

crates/openshell-server/src/auth/guard.rs

@@ -9,6 +9,7 @@
 //! already evaluated.
 
 use super::principal::Principal;
+use super::principal::SandboxPrincipal;
 use tonic::Status;
 use tracing::info;
 
@@ -66,6 +67,32 @@ pub fn enforce_sandbox_scope<T>(
     Ok(principal)
 }
 
+/// Require a sandbox principal and reject users or anonymous callers.
+///
+/// Supervisor-only control/data plane RPCs (`ConnectSupervisor`,
+/// `RelayStream`) must be presented by the sandbox supervisor itself.
+/// User principals intentionally pass [`ensure_sandbox_scope`] for normal
+/// CLI/TUI APIs because RBAC is their gate, but they are not valid
+/// supervisor identities.
+#[allow(clippy::result_large_err)]
+pub fn ensure_sandbox_principal_scope(
+    principal: &Principal,
+    claimed_sandbox_id: &str,
+) -> Result<SandboxPrincipal, Status> {
+    match principal {
+        Principal::Sandbox(p) => {
+            ensure_sandbox_scope(principal, claimed_sandbox_id)?;
+            Ok(p.clone())
+        }
+        Principal::User(_) => Err(Status::permission_denied(
+            "supervisor RPCs require a sandbox principal",
+        )),
+        Principal::Anonymous => Err(Status::unauthenticated(
+            "supervisor RPCs require an authenticated sandbox principal",
+        )),
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -119,6 +146,20 @@ mod tests {
         assert_eq!(err.code(), tonic::Code::Unauthenticated);
     }
 
+    #[test]
+    fn sandbox_principal_scope_returns_matching_sandbox() {
+        let principal = sandbox("sbx-1");
+        let scoped = ensure_sandbox_principal_scope(&principal, "sbx-1").expect("scope OK");
+        assert_eq!(scoped.sandbox_id, "sbx-1");
+    }
+
+    #[test]
+    fn sandbox_principal_scope_rejects_users() {
+        let err = ensure_sandbox_principal_scope(&user("alice"), "sbx-1")
+            .expect_err("users are not supervisor identities");
+        assert_eq!(err.code(), tonic::Code::PermissionDenied);
+    }
+
     #[test]
     fn enforce_reads_from_request_extensions() {
         let mut req = tonic::Request::new(());

crates/openshell-server/src/auth/mod.rs

@@ -17,5 +17,6 @@ pub mod k8s_sa;
 pub mod oidc;
 pub mod principal;
 pub mod sandbox_jwt;
+pub mod sandbox_methods;
 
 pub use http::router;

crates/openshell-server/src/auth/oidc.rs

@@ -356,7 +356,7 @@ impl JwksCache {
 ///
 /// Returns `Ok(None)` when no Bearer header is present, so the chain can fall
 /// through to other authenticators (e.g. the gateway-minted sandbox JWT
-/// authenticator added in PR 2).
+/// authenticator).
 pub struct OidcAuthenticator {
     cache: Arc<JwksCache>,
 }

crates/openshell-server/src/auth/principal.rs

@@ -26,7 +26,7 @@ pub enum Principal {
     User(UserPrincipal),
     /// Sandbox supervisor authenticated by an identity bound to a specific
     /// sandbox UUID. The wrapped `sandbox_id` MUST match any sandbox referenced
-    /// in the request body for sandbox-class methods (PR-4 guard).
+    /// in the request body for sandbox-class methods.
     Sandbox(#[allow(dead_code)] SandboxPrincipal),
     /// Truly unauthenticated caller (health probes, reflection). Sandbox-class
     /// and user-class methods reject this variant.
@@ -43,17 +43,14 @@ pub struct UserPrincipal {
 
 /// Sandbox caller — bound to one specific sandbox UUID.
 ///
-/// `sandbox_id` and `source` are consumed by the PR-4 handler guard; until
-/// then they only exist in the type so the trait shape is stable across the
-/// PR series.
+/// `sandbox_id` and `source` are consumed by the router and handler guards.
 #[derive(Debug, Clone)]
 #[allow(dead_code)]
 pub struct SandboxPrincipal {
-    /// Canonical sandbox UUID. Empty string only for the PR-1 legacy marker;
-    /// PR 2 onwards always populates this from a verified credential.
+    /// Canonical sandbox UUID populated from a verified sandbox credential.
     pub sandbox_id: String,
-    /// How this principal was verified — used for audit logs and to gate the
-    /// PR-4 IDOR check against unverified sources.
+    /// How this principal was verified — used for audit logs and method-specific
+    /// authorization checks.
     pub source: SandboxIdentitySource,
     /// SPIFFE trust domain. Populated when the credential is SPIFFE-shaped;
     /// reserved for future per-sandbox cert / SPIRE authenticators.
@@ -63,18 +60,17 @@ pub struct SandboxPrincipal {
 /// How a [`SandboxPrincipal`] was authenticated.
 ///
 /// Variant fields are populated by the producing authenticator and consumed
-/// by audit logging + the PR-4 IDOR guard. Until PR 4 lands those readers
-/// they look unused to the dead-code lint.
+/// by audit logging and method-specific authorization checks.
 #[derive(Debug, Clone)]
 #[allow(dead_code)]
 pub enum SandboxIdentitySource {
     /// Gateway-minted JWT validated against the gateway's signing key.
     /// Produced by [`super::sandbox_jwt::SandboxJwtAuthenticator`].
     BootstrapJwt { issuer: String },
-    /// Per-sandbox client certificate. Reserved for the v2 channel-bound
-    /// identity follow-up.
+    /// Per-sandbox client certificate. Reserved for channel-bound sandbox
+    /// identity.
     BootstrapCert { fingerprint: String },
-    /// SPIRE-issued SVID. Reserved for the SPIFFE/SPIRE follow-up.
+    /// SPIRE-issued SVID. Reserved for SPIFFE/SPIRE sandbox identity.
     SpiffeSvid { spiffe_id: String },
     /// K8s `ServiceAccount` token used to bootstrap a gateway-minted JWT
     /// via `IssueSandboxToken`. Populated only on that one RPC path.

crates/openshell-server/src/auth/sandbox_jwt.rs

@@ -5,7 +5,7 @@
 //!
 //! The gateway signs an Ed25519 JWT for each sandbox at create time and
 //! the sandbox supervisor presents it as `Authorization: Bearer <jwt>` on
-//! every gRPC call (PR 3). This module implements both sides of the
+//! supervisor-to-gateway gRPC calls. This module implements both sides of the
 //! gateway-controlled token:
 //! - [`SandboxJwtIssuer`] mints fresh tokens (called from
 //!   `handle_create_sandbox` and the `IssueSandboxToken` RPC).

crates/openshell-server/src/auth/sandbox_methods.rs

@@ -0,0 +1,60 @@
+// SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+//! Method-level allowlist for sandbox principals.
+//!
+//! Gateway-minted sandbox JWTs identify a single sandbox supervisor. They
+//! must not authorize user-facing or admin APIs. The router rejects sandbox
+//! principals for every method outside this supervisor-to-gateway allowlist;
+//! handlers still perform same-sandbox checks on request bodies.
+
+/// Methods a `Principal::Sandbox` may invoke.
+const ALLOWED_SANDBOX_METHODS: &[&str] = &[
+    "/openshell.v1.OpenShell/IssueSandboxToken",
+    "/openshell.v1.OpenShell/RefreshSandboxToken",
+    "/openshell.v1.OpenShell/ConnectSupervisor",
+    "/openshell.v1.OpenShell/RelayStream",
+    "/openshell.v1.OpenShell/GetSandboxConfig",
+    "/openshell.v1.OpenShell/GetSandboxProviderEnvironment",
+    "/openshell.v1.OpenShell/UpdateConfig",
+    "/openshell.v1.OpenShell/ReportPolicyStatus",
+    "/openshell.v1.OpenShell/PushSandboxLogs",
+    "/openshell.v1.OpenShell/SubmitPolicyAnalysis",
+    "/openshell.v1.OpenShell/GetDraftPolicy",
+];
+
+pub fn is_sandbox_callable(path: &str) -> bool {
+    ALLOWED_SANDBOX_METHODS.contains(&path)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn supervisor_callbacks_are_allowed() {
+        assert!(is_sandbox_callable(
+            "/openshell.v1.OpenShell/ConnectSupervisor"
+        ));
+        assert!(is_sandbox_callable("/openshell.v1.OpenShell/RelayStream"));
+        assert!(is_sandbox_callable(
+            "/openshell.v1.OpenShell/GetSandboxConfig"
+        ));
+    }
+
+    #[test]
+    fn user_and_admin_methods_are_not_allowed() {
+        assert!(!is_sandbox_callable(
+            "/openshell.v1.OpenShell/ListSandboxes"
+        ));
+        assert!(!is_sandbox_callable(
+            "/openshell.v1.OpenShell/DeleteSandbox"
+        ));
+        assert!(!is_sandbox_callable(
+            "/openshell.v1.OpenShell/CreateProvider"
+        ));
+        assert!(!is_sandbox_callable(
+            "/openshell.v1.OpenShell/ApproveDraftChunk"
+        ));
+    }
+}

crates/openshell-server/src/cli.rs

@@ -336,11 +336,10 @@ async fn run_from_args(mut args: RunArgs, matches: ArgMatches) -> Result<()> {
         });
     }
 
-    // PR-2 wires gateway_jwt via the config file only — there's no CLI
-    // flag yet because the standard deployments (helm chart + RPM init
-    // script) drop the keypair to a known path and pass that path through
-    // the TOML. A CLI shortcut can be added if a singleplayer operator
-    // needs to override.
+    // `gateway_jwt` is configured through TOML. Standard deployments
+    // (helm chart + RPM init script) drop the keypair to a known path and
+    // pass that path through the file. A CLI shortcut can be added if a
+    // singleplayer operator needs to override it.
     if let Some(jwt) = file
         .as_ref()
         .and_then(|f| f.openshell.gateway.gateway_jwt.clone())

crates/openshell-server/src/grpc/policy.rs

@@ -2901,9 +2901,9 @@ mod tests {
     use std::sync::Arc;
     use tonic::Code;
 
-    /// Wrap a request with a user `Principal` so handlers' scope guards
-    /// (introduced in PR 4) treat the test caller as a CLI user — equivalent
-    /// to the pre-PR-4 behavior where all tests effectively ran as user.
+    /// Wrap a request with a user `Principal` so handler scope guards treat
+    /// the test caller as a CLI user. Most handler tests exercise
+    /// user-facing behavior and should not trip sandbox equality checks.
     fn with_user<T>(mut request: Request<T>) -> Request<T> {
         request
             .extensions_mut()
@@ -3000,7 +3000,7 @@ mod tests {
         assert!(!is_sandbox_caller(&req));
     }
 
-    // ---- PR-4 IDOR guard (issue #1354) ----
+    // ---- Sandbox IDOR guard (issue #1354) ----
 
     #[tokio::test]
     async fn cross_sandbox_get_sandbox_config_denied() {