feat(supervisor-middleware): add network egress middleware

Cargo.toml

@@ -74,6 +74,7 @@ serde_yml = "0.0.12"
 toml = "0.8"
 apollo-parser = "0.8.5"
 tower-mcp-types = "0.12.0"
+regex = "1"
 
 # HTTP client
 reqwest = { version = "0.12", default-features = false, features = ["json", "rustls-tls-native-roots"] }

architecture/gateway.md

@@ -271,6 +271,14 @@ config path. A gateway-global policy can override sandbox-scoped policy. The
 sandbox supervisor polls for config revisions and hot-reloads dynamic policy
 when the policy engine accepts the update.
 
+External supervisor middleware registration is operator-owned gateway
+configuration. At startup the gateway connects to each service, validates its
+described bindings and operator body limit, and rejects duplicate binding IDs.
+Before persisting a policy, the gateway asks each selected implementation to
+validate its config. The effective sandbox config contains only the registered
+services required by that policy; supervisors invoke those services directly on
+the request path.
+
 Provider credential expiry is enforced during gateway-to-sandbox credential
 resolution and again by the sandbox placeholder resolver. This keeps expired
 credentials from resolving even when a running sandbox still has retained

architecture/sandbox.md

@@ -66,6 +66,21 @@ matchers; generic JSON-RPC rules match only the method.
 JSON-RPC responses and server-to-client MCP messages on response or SSE streams
 are relayed but are not currently parsed for policy enforcement.
 
+For admitted HTTP requests, the proxy can run an ordered supervisor middleware
+chain before credential injection. Host selectors choose the chain independently
+of the network rule that admitted the request. Policy entries use integer order
+values with stable name tie-breaking, and the gRPC contract represents operations
+and phases as enums. Built-ins run in-process;
+operator-registered services are called directly from the supervisor
+over the common middleware gRPC contract. The gateway validates external
+service capabilities and policy-owned config before delivery. Supervisors keep
+the last-known-good service registry when a live config reload fails. Built-in
+middleware identifiers, host-selector matching, and pure config validation live
+in `openshell-core` so policy admission does not depend on the supervisor
+runtime implementation. The policy and runtime also share the core
+JSON/protobuf adapter for middleware configuration, keeping serialization
+consistent across that boundary.
+
 `https://inference.local` is special. It bypasses OPA network policy and is
 handled by the inference interception path:
 
@@ -176,6 +191,8 @@ quickly.
 - If gateway config polling fails, the sandbox keeps its last-known-good policy.
 - If a live policy update is invalid, the supervisor rejects it and keeps the
   current policy.
+- If an operator-run middleware call fails, the selected config's `on_error`
+  behavior decides whether to deny the request or continue without that stage.
 - Existing raw byte streams are connection scoped. Dynamic policy changes apply
   to new connections or the next parsed HTTP request where the proxy can safely
   re-evaluate.

crates/openshell-cli/src/run.rs

@@ -1648,39 +1648,9 @@ fn parse_driver_config_json(value: &str) -> Result<prost_types::Struct> {
         ));
     };
 
-    Ok(prost_types::Struct {
-        fields: fields
-            .into_iter()
-            .map(|(key, value)| json_to_protobuf_value(value).map(|value| (key, value)))
-            .collect::<Result<_>>()?,
-    })
-}
-
-fn json_to_protobuf_value(value: serde_json::Value) -> Result<prost_types::Value> {
-    use prost_types::{ListValue, Struct, Value, value::Kind};
-
-    let kind = match value {
-        serde_json::Value::Null => Kind::NullValue(0),
-        serde_json::Value::Bool(value) => Kind::BoolValue(value),
-        serde_json::Value::Number(value) => Kind::NumberValue(value.as_f64().ok_or_else(|| {
-            miette!("--driver-config-json contains a number that cannot be represented")
-        })?),
-        serde_json::Value::String(value) => Kind::StringValue(value),
-        serde_json::Value::Array(values) => Kind::ListValue(ListValue {
-            values: values
-                .into_iter()
-                .map(json_to_protobuf_value)
-                .collect::<Result<_>>()?,
-        }),
-        serde_json::Value::Object(fields) => Kind::StructValue(Struct {
-            fields: fields
-                .into_iter()
-                .map(|(key, value)| json_to_protobuf_value(value).map(|value| (key, value)))
-                .collect::<Result<_>>()?,
-        }),
-    };
-
-    Ok(Value { kind: Some(kind) })
+    openshell_core::proto_struct::json_object_to_struct(fields)
+        .into_diagnostic()
+        .wrap_err("--driver-config-json contains a value that cannot be represented")
 }
 
 fn validate_cpu_quantity(value: &str) -> Result<String> {

crates/openshell-core/Cargo.toml

@@ -11,6 +11,7 @@ license.workspace = true
 repository.workspace = true
 
 [dependencies]
+glob = { workspace = true }
 prost = { workspace = true }
 prost-types = { workspace = true }
 tonic = { workspace = true, features = ["channel", "tls-native-roots"] }

crates/openshell-core/README.md

@@ -50,3 +50,17 @@ router agree on provider defaults. Profiles define:
 
 Do not duplicate provider-specific inference behavior in callers. Add shared
 behavior here, then consume it from the gateway, sandbox, and router.
+
+## Middleware Contracts
+
+Built-in supervisor middleware identifiers, host-selector matching, and pure
+configuration validation live in `openshell_core::middleware`. Policy admission
+and the supervisor runtime consume the same contract without introducing a
+dependency from the policy crate to the supervisor implementation.
+
+## Protobuf Struct Conversion
+
+Use `openshell_core::proto_struct` when crossing between `serde_json` values and
+`prost_types::{Struct, Value}`. Both conversion directions live in this module;
+JSON-to-protobuf conversion is fallible so callers cannot silently replace an
+unrepresentable number.

crates/openshell-core/src/grpc_client.rs

@@ -24,11 +24,11 @@ use std::time::{Duration, SystemTime, UNIX_EPOCH};
 
 use crate::proto::{
     DenialSummary, GetDraftPolicyRequest, GetInferenceBundleRequest, GetInferenceBundleResponse,
-    GetSandboxConfigRequest, GetSandboxProviderEnvironmentRequest, IssueSandboxTokenRequest,
-    NetworkActivitySummary, PolicyChunk, PolicySource, PolicyStatus, RefreshSandboxTokenRequest,
-    ReportPolicyStatusRequest, SandboxPolicy as ProtoSandboxPolicy, SubmitPolicyAnalysisRequest,
-    SubmitPolicyAnalysisResponse, UpdateConfigRequest, inference_client::InferenceClient,
-    open_shell_client::OpenShellClient,
+    GetSandboxConfigRequest, GetSandboxConfigResponse, GetSandboxProviderEnvironmentRequest,
+    IssueSandboxTokenRequest, NetworkActivitySummary, PolicyChunk, PolicySource, PolicyStatus,
+    RefreshSandboxTokenRequest, ReportPolicyStatusRequest, SandboxPolicy as ProtoSandboxPolicy,
+    SubmitPolicyAnalysisRequest, SubmitPolicyAnalysisResponse, UpdateConfigRequest,
+    inference_client::InferenceClient, open_shell_client::OpenShellClient,
 };
 use crate::sandbox_env;
 use miette::{IntoDiagnostic, Result, WrapErr};
@@ -573,19 +573,36 @@ pub async fn fetch_policy(endpoint: &str, sandbox_id: &str) -> Result<Option<Pro
     fetch_policy_with_client(&mut client, sandbox_id).await
 }
 
-/// Fetch sandbox policy using an existing client connection.
-async fn fetch_policy_with_client(
+/// Fetch the complete effective sandbox configuration, including external
+/// middleware registrations required by the policy.
+pub async fn fetch_sandbox_config(
+    endpoint: &str,
+    sandbox_id: &str,
+) -> Result<GetSandboxConfigResponse> {
+    debug!(endpoint = %endpoint, sandbox_id = %sandbox_id, "Connecting to OpenShell server");
+    let mut client = connect(endpoint).await?;
+    fetch_sandbox_config_with_client(&mut client, sandbox_id).await
+}
+
+async fn fetch_sandbox_config_with_client(
     client: &mut OpenShellClient<AuthedChannel>,
     sandbox_id: &str,
-) -> Result<Option<ProtoSandboxPolicy>> {
-    let response = client
+) -> Result<GetSandboxConfigResponse> {
+    client
         .get_sandbox_config(GetSandboxConfigRequest {
             sandbox_id: sandbox_id.to_string(),
         })
         .await
-        .into_diagnostic()?;
+        .map(tonic::Response::into_inner)
+        .into_diagnostic()
+}
 
-    let inner = response.into_inner();
+/// Fetch sandbox policy using an existing client connection.
+async fn fetch_policy_with_client(
+    client: &mut OpenShellClient<AuthedChannel>,
+    sandbox_id: &str,
+) -> Result<Option<ProtoSandboxPolicy>> {
+    let inner = fetch_sandbox_config_with_client(client, sandbox_id).await?;
 
     // version 0 with no policy means the sandbox was created without one.
     if inner.version == 0 && inner.policy.is_none() {
@@ -711,6 +728,7 @@ pub struct SettingsPollResult {
     /// When `policy_source` is `Global`, the version of the global policy revision.
     pub global_policy_version: u32,
     pub provider_env_revision: u64,
+    pub supervisor_middleware_services: Vec<crate::proto::SupervisorMiddlewareService>,
 }
 
 pub struct ProviderEnvironmentResult {
@@ -755,6 +773,7 @@ impl CachedOpenShellClient {
             settings: inner.settings,
             global_policy_version: inner.global_policy_version,
             provider_env_revision: inner.provider_env_revision,
+            supervisor_middleware_services: inner.supervisor_middleware_services,
         })
     }
 

crates/openshell-core/src/lib.rs

@@ -23,6 +23,7 @@ pub mod grpc_client;
 pub mod image;
 pub mod inference;
 pub mod metadata;
+pub mod middleware;
 pub mod net;
 pub mod paths;
 pub mod policy;

crates/openshell-core/src/middleware.rs

@@ -0,0 +1,108 @@
+// SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+//! Shared supervisor middleware identifiers and policy validation contracts.
+
+use miette::{Result, miette};
+
+/// Binding identifier for the built-in secret redaction middleware.
+pub const BUILTIN_SECRETS: &str = "openshell/secrets";
+
+/// Match a middleware host selector pattern using the runtime's glob semantics.
+///
+/// Matching is case-insensitive. Invalid or empty patterns return an error
+/// instead of silently becoming a non-match.
+pub fn host_matches(pattern: &str, host: &str) -> std::result::Result<bool, String> {
+    if pattern.is_empty() {
+        return Err("host pattern must not be empty".to_string());
+    }
+    if pattern.chars().any(char::is_whitespace) {
+        return Err("host pattern must not contain whitespace".to_string());
+    }
+
+    let pattern = glob::Pattern::new(&pattern.to_ascii_lowercase())
+        .map_err(|error| format!("invalid host pattern: {error}"))?;
+    Ok(pattern.matches(&host.to_ascii_lowercase()))
+}
+
+/// Validate policy-owned configuration for a built-in middleware.
+pub fn validate_builtin_config(implementation: &str, config: &prost_types::Struct) -> Result<()> {
+    match implementation {
+        BUILTIN_SECRETS => validate_secrets_config(config),
+        other => Err(miette!(
+            "middleware implementation '{other}' is not available in phase 1"
+        )),
+    }
+}
+
+fn validate_secrets_config(config: &prost_types::Struct) -> Result<()> {
+    let mode = config
+        .fields
+        .get("secrets")
+        .and_then(|value| match value.kind.as_ref() {
+            Some(prost_types::value::Kind::StringValue(value)) => Some(value.as_str()),
+            _ => None,
+        })
+        .unwrap_or("redact");
+    if mode != "redact" {
+        return Err(miette!(
+            "{BUILTIN_SECRETS} only supports config.secrets: redact in phase 1"
+        ));
+    }
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn host_matching_is_case_insensitive() {
+        assert!(host_matches("*.Example.COM", "API.example.com").unwrap());
+        assert!(!host_matches("*.example.com", "example.com").unwrap());
+        assert!(host_matches("*", "deep.api.example.com").unwrap());
+    }
+
+    #[test]
+    fn host_matching_rejects_invalid_patterns() {
+        assert!(host_matches("", "api.example.com").is_err());
+        assert!(host_matches("api .example.com", "api.example.com").is_err());
+        assert!(host_matches("api[.example.com", "api.example.com").is_err());
+    }
+
+    #[test]
+    fn secrets_config_defaults_to_redact() {
+        validate_builtin_config(BUILTIN_SECRETS, &prost_types::Struct::default()).unwrap();
+    }
+
+    #[test]
+    fn secrets_config_rejects_unsupported_mode() {
+        let config = prost_types::Struct {
+            fields: std::iter::once((
+                "secrets".to_string(),
+                prost_types::Value {
+                    kind: Some(prost_types::value::Kind::StringValue("allow".into())),
+                },
+            ))
+            .collect(),
+        };
+
+        let error = validate_builtin_config(BUILTIN_SECRETS, &config).unwrap_err();
+        assert!(
+            error
+                .to_string()
+                .contains("only supports config.secrets: redact")
+        );
+    }
+
+    #[test]
+    fn rejects_unknown_builtin() {
+        let error = validate_builtin_config("openshell/unknown", &prost_types::Struct::default())
+            .unwrap_err();
+        assert!(
+            error
+                .to_string()
+                .contains("implementation 'openshell/unknown' is not available")
+        );
+    }
+}

crates/openshell-core/src/proto/mod.rs

@@ -79,8 +79,22 @@ pub mod inference {
     }
 }
 
+#[allow(
+    clippy::all,
+    clippy::pedantic,
+    clippy::nursery,
+    unused_qualifications,
+    rust_2018_idioms
+)]
+pub mod middleware {
+    pub mod v1 {
+        include!(concat!(env!("OUT_DIR"), "/openshell.middleware.v1.rs"));
+    }
+}
+
 pub use datamodel::v1::*;
 pub use inference::v1::*;
+pub use middleware::v1::*;
 pub use openshell::*;
 pub use sandbox::v1::*;
 pub use test::ObjectForTest;