feat(provider): selective credential passthrough

Add an opt-in passthrough mechanism for provider credentials that bypass the
canonical openshell:resolve:env:* placeholder and L7 proxy substitution.

Provider gains a repeated string passthrough_credentials field listing
credential keys whose real value should be injected directly into the agent
process environment. Required for SDKs that validate credential format
in-process (Slack xoxb-*/xapp-*), credentials consumed by in-process crypto
(HMAC signing secrets, signature verification), and transports the proxy
cannot rewrite (WebSocket payloads after HTTP 101 upgrade). Passthrough
drops the "agent never sees the real secret" invariant for the listed
keys; documented as a per-credential security trade-off.

Server: validation rejects keys not in credentials, invalid env var names,
duplicates, and over-cap. resolve_provider_environment returns a
ProviderEnvironment struct with the merged env map and the union of
passthrough keys; passthrough flag follows the winning value on duplicate
keys across providers. Update merge auto-prunes orphaned passthrough
entries when their credential is deleted in the same call (proto3 cannot
distinguish "field unset" from "set to empty list"), preserving the
"recover via update" path. Explicit non-empty incoming list still rejects
orphans as a caller bug.

Sandbox: SecretResolver::from_provider_env_with_passthrough handles the
new mode — passthrough keys go to child env as real values, resolver does
not learn them; non-passthrough keys still get the canonical placeholder.

CLI: provider create/update accept --passthrough KEY (repeatable);
provider get annotates passthrough keys, provider list adds a PASSTHROUGH
column.

Refs #894 (selective passthrough lands; custom-format placeholders deferred
to a follow-up).

Signed-off-by: Tinson Lai <tinsonl@nvidia.com>

Author: laitingsheng

architecture/sandbox-providers.md

@@ -35,6 +35,9 @@ Provider is defined in `proto/datamodel.proto`:
 - `type`: canonical provider slug (`claude`, `gitlab`, `github`, etc.)
 - `credentials`: `map<string, string>` for secret values
 - `config`: `map<string, string>` for non-secret settings
+- `passthrough_credentials`: `repeated string` listing credential keys whose
+  real value is injected directly into the agent process, bypassing the
+  canonical placeholder substitution (see [Selective Passthrough](#selective-passthrough)).
 
 The gRPC surface is defined in `proto/openshell.proto`:
 
@@ -363,6 +366,92 @@ CLI: openshell sandbox create -- claude
                       +-- Proxy rewrites outbound auth header placeholders -> real secrets
 ```
 
+## Selective Passthrough
+
+The canonical placeholder model breaks for credentials that:
+
+- are validated **in-process** by an SDK before any network call (Slack
+  `@slack/web-api` checks the `xoxb-` prefix; `@slack/socket-mode` checks
+  `xapp-`; OAuth libraries parse JWT structure; AWS SDKs validate access-key
+  format),
+- are sent over **transports the L7 proxy cannot rewrite** (WebSocket payloads
+  after HTTP `101 Switching Protocols` upgrade — for example Discord's
+  IDENTIFY frame), or
+- are consumed by **in-process crypto** that never reaches the wire (Slack
+  signing-secret HMAC, Discord interaction-signature verification).
+
+For these cases the operator can opt specific credential keys into
+**passthrough**: the supervisor injects the **real value** into the agent's
+environment instead of the canonical
+`openshell:resolve:env:<KEY>` placeholder, and the resolver does not learn
+that key. The L7 proxy therefore performs no substitution for it.
+
+### Configuration
+
+Each entry in `Provider.passthrough_credentials` must:
+
+- be a valid environment-variable name (matches `^[A-Za-z_][A-Za-z0-9_]*$`),
+- be present as a key in `Provider.credentials`,
+- appear at most once.
+
+The gateway rejects updates that violate any of these conditions.
+
+**Update merge semantics.** Proto3 cannot distinguish "field unset" from
+"field set to empty list" for repeated strings, so the gateway uses a
+two-mode merge:
+
+- **Empty incoming list** (caller is not declaring passthrough) — preserve
+  the existing list, but auto-prune any entries whose credential was deleted
+  in the same update. Without this prune, marking a credential passthrough
+  and then deleting that credential would lock the provider in an invalid
+  state.
+- **Non-empty incoming list** — replace the stored list verbatim. Strict
+  validation still applies, so an explicit entry naming a non-existent
+  credential is rejected (treated as a caller bug, not a state-rescue
+  request).
+
+**Clearing the list.** Because proto3 cannot signal "set to empty" for
+repeated strings, there is no direct update that wipes the passthrough
+list while leaving credentials intact. Available paths:
+
+- delete the underlying credentials (auto-prune removes the corresponding
+  passthrough entries),
+- replace the list with a non-empty subset (send the entries you want to
+  keep), or
+- recreate the provider.
+
+### Resolution and merge across providers
+
+`resolve_provider_environment()` collects credentials and the union of
+passthrough keys across all providers attached to a sandbox. When two providers
+declare the same credential key, the first provider's value wins (existing
+semantics) and the passthrough flag follows the **winning** value: a
+passthrough opt-in declared on the second provider has no effect.
+
+### Supervisor injection
+
+`SecretResolver::from_provider_env_with_passthrough()` consumes both the env
+map and the passthrough key list. For each credential:
+
+- key in passthrough list → child env receives the real value; resolver does
+  not register a placeholder entry;
+- otherwise → child env receives the canonical placeholder and the resolver
+  maps it to the real value for on-the-wire substitution.
+
+If every key is passthrough the resolver is `None` and no L7 substitution
+runs.
+
+### Security trade-off
+
+Passthrough drops the "agent never sees the real secret" invariant for the
+listed keys. The real value is at rest in `/proc/<agent-pid>/environ` and any
+descendant process inherits it. Use sparingly:
+
+- prefer canonical placeholders whenever the consumer permits it;
+- only opt in keys whose consumer demonstrably fails with the placeholder
+  (in-process format check, opaque transport, in-process crypto);
+- document each opt-in in the provider's deployment notes.
+
 ## Persistence and Validation
 
 The gateway enforces:

crates/openshell-cli/src/main.rs

@@ -709,6 +709,15 @@ enum ProviderCommands {
         /// Provider config key/value pair.
         #[arg(long = "config", value_name = "KEY=VALUE")]
         config: Vec<String>,
+
+        /// Credential key whose real value is injected directly into the
+        /// agent process, bypassing the canonical placeholder substitution
+        /// and L7 proxy rewriting. Each key must also appear in `--credential`
+        /// (or be discovered via `--from-existing`). Drops the "agent never
+        /// sees the real secret" invariant for that key — see provider docs
+        /// for the security trade-off.
+        #[arg(long = "passthrough", value_name = "KEY")]
+        passthrough: Vec<String>,
     },
 
     /// Fetch a provider by name.
@@ -757,6 +766,15 @@ enum ProviderCommands {
         /// Provider config key/value pair.
         #[arg(long = "config", value_name = "KEY=VALUE")]
         config: Vec<String>,
+
+        /// Credential key whose real value is injected directly into the
+        /// agent process, bypassing the canonical placeholder substitution
+        /// and L7 proxy rewriting. Replaces the existing passthrough list
+        /// when non-empty. Each key must also be present in the merged
+        /// credentials. Drops the "agent never sees the real secret"
+        /// invariant for that key.
+        #[arg(long = "passthrough", value_name = "KEY")]
+        passthrough: Vec<String>,
     },
 
     /// Delete providers by name.
@@ -2742,6 +2760,7 @@ async fn main() -> Result<()> {
                     from_existing,
                     credentials,
                     config,
+                    passthrough,
                 } => {
                     run::provider_create(
                         endpoint,
@@ -2750,6 +2769,7 @@ async fn main() -> Result<()> {
                         from_existing,
                         &credentials,
                         &config,
+                        &passthrough,
                         &tls,
                     )
                     .await?;
@@ -2769,13 +2789,15 @@ async fn main() -> Result<()> {
                     from_existing,
                     credentials,
                     config,
+                    passthrough,
                 } => {
                     run::provider_update(
                         endpoint,
                         &name,
                         from_existing,
                         &credentials,
                         &config,
+                        &passthrough,
                         &tls,
                     )
                     .await?;

crates/openshell-cli/src/run.rs

@@ -3576,6 +3576,7 @@ async fn auto_create_provider(
                 r#type: provider_type.to_string(),
                 credentials: discovered.credentials.clone(),
                 config: discovered.config.clone(),
+                passthrough_credentials: Vec::new(),
             }),
         };
 
@@ -3616,6 +3617,7 @@ async fn auto_create_provider(
                     r#type: provider_type.to_string(),
                     credentials: discovered.credentials.clone(),
                     config: discovered.config.clone(),
+                    passthrough_credentials: Vec::new(),
                 }),
             };
 
@@ -3676,6 +3678,50 @@ fn parse_key_value_pairs(items: &[String], flag: &str) -> Result<HashMap<String,
     Ok(map)
 }
 
+/// Parse `--passthrough KEY` flags into a deduplicated list. Validates that
+/// each entry is non-empty and that no key is supplied more than once.
+///
+/// Cross-referencing against the credential map is intentionally not done
+/// here — call [`ensure_passthrough_in_credentials`] when the caller has the
+/// full local credential set (e.g. on `provider create` after
+/// `--from-existing` discovery). On `provider update` the credential set
+/// lives only on the server, and the server re-validates anyway.
+fn parse_passthrough_keys(items: &[String]) -> Result<Vec<String>> {
+    let mut seen = HashSet::new();
+    let mut out = Vec::with_capacity(items.len());
+    for item in items {
+        let key = item.trim();
+        if key.is_empty() {
+            return Err(miette::miette!("--passthrough key cannot be empty"));
+        }
+        if !seen.insert(key.to_string()) {
+            return Err(miette::miette!(
+                "--passthrough key '{key}' was supplied more than once"
+            ));
+        }
+        out.push(key.to_string());
+    }
+    Ok(out)
+}
+
+/// Reject any passthrough key that is not present in `credential_map`. The
+/// caller is responsible for assembling the full local credential set before
+/// invoking — typically explicit `--credential` entries merged with anything
+/// `--from-existing` discovered.
+fn ensure_passthrough_in_credentials(
+    passthrough: &[String],
+    credential_map: &HashMap<String, String>,
+) -> Result<()> {
+    for key in passthrough {
+        if !credential_map.contains_key(key) {
+            return Err(miette::miette!(
+                "--passthrough '{key}' is not present in resolved credentials"
+            ));
+        }
+    }
+    Ok(())
+}
+
 fn parse_credential_pairs(items: &[String]) -> Result<HashMap<String, String>> {
     let mut map = HashMap::new();
 
@@ -3712,13 +3758,15 @@ fn parse_credential_pairs(items: &[String]) -> Result<HashMap<String, String>> {
     Ok(map)
 }
 
+#[allow(clippy::too_many_arguments)] // user-facing CLI command
 pub async fn provider_create(
     server: &str,
     name: &str,
     provider_type: &str,
     from_existing: bool,
     credentials: &[String],
     config: &[String],
+    passthrough: &[String],
     tls: &TlsOptions,
 ) -> Result<()> {
     if from_existing && !credentials.is_empty() {
@@ -3735,6 +3783,7 @@ pub async fn provider_create(
 
     let mut credential_map = parse_credential_pairs(credentials)?;
     let mut config_map = parse_key_value_pairs(config, "--config")?;
+    let passthrough_credentials = parse_passthrough_keys(passthrough)?;
 
     if from_existing {
         let registry = ProviderRegistry::new();
@@ -3762,6 +3811,11 @@ pub async fn provider_create(
         ));
     }
 
+    // The full credential set is known locally on create (--credential plus
+    // anything --from-existing discovered), so cross-check passthrough keys
+    // here for fast feedback. The server re-validates regardless.
+    ensure_passthrough_in_credentials(&passthrough_credentials, &credential_map)?;
+
     let response = client
         .create_provider(CreateProviderRequest {
             provider: Some(Provider {
@@ -3774,6 +3828,7 @@ pub async fn provider_create(
                 r#type: provider_type,
                 credentials: credential_map,
                 config: config_map,
+                passthrough_credentials,
             }),
         })
         .await
@@ -3806,8 +3861,25 @@ pub async fn provider_get(server: &str, name: &str, tls: &TlsOptions) -> Result<
         .provider
         .ok_or_else(|| miette::miette!("provider missing from response"))?;
 
-    let credential_keys = provider.credentials.keys().cloned().collect::<Vec<_>>();
-    let config_keys = provider.config.keys().cloned().collect::<Vec<_>>();
+    let passthrough: HashSet<&str> = provider
+        .passthrough_credentials
+        .iter()
+        .map(String::as_str)
+        .collect();
+    let mut credential_keys = provider
+        .credentials
+        .keys()
+        .map(|k| {
+            if passthrough.contains(k.as_str()) {
+                format!("{k} (passthrough)")
+            } else {
+                k.clone()
+            }
+        })
+        .collect::<Vec<_>>();
+    credential_keys.sort();
+    let mut config_keys = provider.config.keys().cloned().collect::<Vec<_>>();
+    config_keys.sort();
 
     println!("{}", "Provider:".cyan().bold());
     println!();
@@ -3878,19 +3950,21 @@ pub async fn provider_list(
         .max(4);
 
     println!(
-        "{:<name_width$}  {:<type_width$}  {:<16}  {}",
+        "{:<name_width$}  {:<type_width$}  {:<16}  {:<13}  {}",
         "NAME".bold(),
         "TYPE".bold(),
         "CREDENTIAL_KEYS".bold(),
+        "PASSTHROUGH".bold(),
         "CONFIG_KEYS".bold(),
     );
 
     for provider in providers {
         println!(
-            "{:<name_width$}  {:<type_width$}  {:<16}  {}",
+            "{:<name_width$}  {:<type_width$}  {:<16}  {:<13}  {}",
             provider.object_name().to_string(),
             provider.r#type,
             provider.credentials.len(),
+            provider.passthrough_credentials.len(),
             provider.config.len(),
         );
     }
@@ -3904,6 +3978,7 @@ pub async fn provider_update(
     from_existing: bool,
     credentials: &[String],
     config: &[String],
+    passthrough: &[String],
     tls: &TlsOptions,
 ) -> Result<()> {
     if from_existing && !credentials.is_empty() {
@@ -3916,6 +3991,11 @@ pub async fn provider_update(
 
     let mut credential_map = parse_credential_pairs(credentials)?;
     let mut config_map = parse_key_value_pairs(config, "--config")?;
+    // On update the local --credential set may legitimately be empty (the
+    // operator is only changing the passthrough list against existing stored
+    // credentials), so the cross-check against credentials is delegated to
+    // server-side validation, which sees the post-merge state.
+    let passthrough_credentials = parse_passthrough_keys(passthrough)?;
 
     if from_existing {
         // Fetch the existing provider to discover its type for credential lookup.
@@ -3960,6 +4040,7 @@ pub async fn provider_update(
                 r#type: String::new(),
                 credentials: credential_map,
                 config: config_map,
+                passthrough_credentials,
             }),
         })
         .await

crates/openshell-cli/tests/ensure_providers_integration.rs

@@ -115,6 +115,7 @@ impl TestOpenShell {
                 r#type: provider_type.to_string(),
                 credentials: HashMap::new(),
                 config: HashMap::new(),
+                passthrough_credentials: Vec::new(),
             },
         );
     }
@@ -293,6 +294,11 @@ impl OpenShell for TestOpenShell {
             r#type: existing.r#type,
             credentials: merge(existing.credentials, provider.credentials),
             config: merge(existing.config, provider.config),
+            passthrough_credentials: if provider.passthrough_credentials.is_empty() {
+                existing.passthrough_credentials
+            } else {
+                provider.passthrough_credentials
+            },
         };
         let updated_name = updated.object_name().to_string();
         providers.insert(updated_name, updated.clone());