Supported authentication path for an out-of-process Rust client to a local mTLS gateway

[dredozubov]

OpenShell’s gateway authentication documentation describes mTLS as the default for local gateways without OIDC. The current SDK transport appears to support server CA configuration while leaving client-certificate mTLS to the CLI path.

What is the intended supported connection path for an out-of-process Rust client?

• an openshell-sdk configuration I missed;
• a lower-level public gRPC client loading the CLI-managed mTLS bundle;
• OIDC or edge authentication instead; or
• planned SDK client-certificate support?

I want to avoid treating plaintext or unauthenticated loopback as a supported integration contract. If this is mainly a documentation gap, I would be happy to contribute a focused clarification or test.

[KirilsTurkins]

Your reading is correct: there is no openshell-sdk::ClientConfig option you missed. The SDK currently states explicitly that it does not implement client-certificate mTLS, and build_channel only supports plaintext, edge-tunnel auth, server-verification bypass, or ordinary HTTPS with an optional CA certificate. Client-certificate mTLS remains in the CLI path.

For an out-of-process Rust client connecting to the default local mTLS gateway today, the public path appears to be:

1. Load the documented per-gateway bundle from ~/.config/openshell/gateways/<name>/mtls/.
2. Build a tonic::transport::Channel with both the server CA and client identity.
3. Pass that channel to openshell_sdk::OpenShellClient::from_parts with a no-op interceptor.

from_parts is specifically documented for channel construction requirements that ClientConfig does not expose.

use std::path::Path;

use openshell_sdk::{EdgeAuthInterceptor, OpenShellClient};
use tonic::transport::{
    Certificate, ClientTlsConfig, Endpoint, Identity,
};

async fn connect_local_mtls(
    endpoint: &str,
    bundle: &Path,
) -> Result<OpenShellClient, Box<dyn std::error::Error>> {
    let ca = tokio::fs::read(bundle.join("ca.crt")).await?;
    let cert = tokio::fs::read(bundle.join("tls.crt")).await?;
    let key = tokio::fs::read(bundle.join("tls.key")).await?;

    let tls = ClientTlsConfig::new()
        .ca_certificate(Certificate::from_pem(ca))
        .identity(Identity::from_pem(cert, key));

    let channel = Endpoint::from_shared(endpoint.to_owned())?
        .tls_config(tls)?
        .connect()
        .await?;

    Ok(OpenShellClient::from_parts(
        channel,
        EdgeAuthInterceptor::noop(),
    ))
}

The generated tonic client is also publicly re-exported as openshell_sdk::raw::GrpcClient, so callers that do not need the curated SDK surface can construct that directly from the same channel.

OIDC and edge authentication are the better fit for shared or remote deployments, but they are not an automatic substitute for the default local mTLS gateway: the gateway must be configured for the chosen mode. If an endpoint requires both a client certificate and an OIDC bearer token, the custom mTLS channel can instead be passed to from_parts with EdgeAuthInterceptor::new(Some(token), None). One caveat is that clients built with from_parts do not receive the SDK’s automatic OIDC refresh behavior.

Plaintext loopback is therefore not required as a fallback. It is a separate, explicitly configured development or trusted-proxy mode, while the documented local default remains mTLS.

I would not currently infer planned native client-certificate fields in ClientConfig; the source comments describe mTLS as intentionally outside the SDK and retained in the CLI until that authentication method is retired. A focused documentation contribution showing the from_parts recipe and clarifying whether the CLI-managed bundle layout is a supported discovery contract for third-party clients would close the present gap.

[sylvesterkaczmarek]

For a local single-user gateway, use the same mTLS bundle as the CLI: ca.crt as the trust root and tls.crt/tls.key as the client identity. With mTLS auth enabled, no separate bearer-token exchange is needed.