NVIDIA
diff --git a/‎AGENTS.md‎
Lines changed: 1 addition & 0 deletions b/‎AGENTS.md‎
Lines changed: 1 addition & 0 deletions
diff --git a/‎Cargo.lock‎
Lines changed: 24 additions & 0 deletions b/‎Cargo.lock‎
Lines changed: 24 additions & 0 deletions
diff --git a/‎crates/openshell-core/src/grpc_client.rs‎
Lines changed: 1 addition & 10 deletions b/‎crates/openshell-core/src/grpc_client.rs‎
Lines changed: 1 addition & 10 deletions
diff --git a/‎crates/openshell-core/src/jwt.rs‎
Lines changed: 65 additions & 0 deletions b/‎crates/openshell-core/src/jwt.rs‎
Lines changed: 65 additions & 0 deletions
diff --git a/‎crates/openshell-core/src/lib.rs‎
Lines changed: 1 addition & 0 deletions b/‎crates/openshell-core/src/lib.rs‎
Lines changed: 1 addition & 0 deletions
diff --git a/‎crates/openshell-sdk/Cargo.toml‎
Lines changed: 37 additions & 0 deletions b/‎crates/openshell-sdk/Cargo.toml‎
Lines changed: 37 additions & 0 deletions
diff --git a/‎crates/openshell-sdk/README.md‎
Lines changed: 69 additions & 0 deletions b/‎crates/openshell-sdk/README.md‎
Lines changed: 69 additions & 0 deletions
diff --git a/‎crates/openshell-sdk/src/auth.rs‎
Lines changed: 112 additions & 0 deletions b/‎crates/openshell-sdk/src/auth.rs‎
Lines changed: 112 additions & 0 deletions
@@ -37,6 +37,7 @@ These pipelines connect skills into end-to-end workflows. Individual skill files
 | `crates/openshell-bootstrap/` | Gateway metadata | Gateway registration metadata, auth token storage, mTLS bundle storage |
 | `crates/openshell-ocsf/` | OCSF logging | OCSF v1.7.0 event types, builders, shorthand/JSONL formatters, tracing layers |
 | `crates/openshell-core/` | Shared core | Common types, configuration, error handling |
+| `crates/openshell-sdk/` | Shared client SDK | Async Rust gateway client (gRPC transport, TLS, OIDC refresh, edge tunnel); consumed by CLI, TUI, and `@openshell/sdk` |
 | `crates/openshell-providers/` | Provider management | Credential provider backends |
 | `crates/openshell-tui/` | Terminal UI | Ratatui-based dashboard for monitoring |
 | `crates/openshell-driver-kubernetes/` | Kubernetes compute driver | In-process `ComputeDriver` backend for K8s sandbox pods |
 
@@ -444,16 +444,7 @@ fn compute_refresh_delay(slot: &TokenSlot) -> Duration {
 /// Returns the expiry in milliseconds since the Unix epoch, or `None` if
 /// the token is not a parseable JWT.
 fn parse_jwt_exp_ms(jwt: &str) -> Option<i64> {
-    use base64::Engine;
-    let mut parts = jwt.splitn(3, '.');
-    let _header = parts.next()?;
-    let payload_b64 = parts.next()?;
-    let decoded = base64::engine::general_purpose::URL_SAFE_NO_PAD
-        .decode(payload_b64)
-        .ok()?;
-    let value: serde_json::Value = serde_json::from_slice(&decoded).ok()?;
-    let exp_secs = value.get("exp")?.as_i64()?;
-    exp_secs.checked_mul(1000)
+    crate::jwt::parse_exp_secs(jwt)?.checked_mul(1000)
 }
 
 #[cfg(test)]
 
@@ -0,0 +1,65 @@
+// SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+//! Minimal, signature-unverified JWT inspection shared by gateway clients.
+//!
+//! Used only for client-side refresh scheduling (deciding when a bearer is
+//! near expiry). It never verifies the signature and must not be used for
+//! any authorization decision. Both the sandbox-side
+//! [`crate::grpc_client`] and the user-facing `openshell-sdk` refresh path
+//! derive token expiry from here so the decode lives in one place.
+
+/// Decode the numeric `exp` claim (Unix seconds) from a JWT payload without
+/// verifying the signature.
+///
+/// Returns `None` when `token` is not a parseable JWT or has no integer `exp`
+/// claim. A leading `Bearer ` prefix is tolerated so callers can pass either a
+/// raw token or an `authorization` header value.
+#[must_use]
+pub fn parse_exp_secs(token: &str) -> Option<i64> {
+    use base64::Engine;
+    let raw = token.strip_prefix("Bearer ").unwrap_or(token);
+    let mut parts = raw.splitn(3, '.');
+    let _header = parts.next()?;
+    let payload_b64 = parts.next()?;
+    let decoded = base64::engine::general_purpose::URL_SAFE_NO_PAD
+        .decode(payload_b64)
+        .ok()?;
+    let value: serde_json::Value = serde_json::from_slice(&decoded).ok()?;
+    value.get("exp")?.as_i64()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use base64::Engine as _;
+
+    fn jwt_with_payload(payload: &serde_json::Value) -> String {
+        let b64 = |bytes: &[u8]| base64::engine::general_purpose::URL_SAFE_NO_PAD.encode(bytes);
+        let header = b64(br#"{"alg":"none","typ":"JWT"}"#);
+        let body = b64(serde_json::to_vec(payload).unwrap().as_slice());
+        format!("{header}.{body}.")
+    }
+
+    #[test]
+    fn reads_integer_exp() {
+        let token = jwt_with_payload(&serde_json::json!({ "exp": 1_900_000_000_i64 }));
+        assert_eq!(parse_exp_secs(&token), Some(1_900_000_000));
+    }
+
+    #[test]
+    fn tolerates_bearer_prefix() {
+        let token = jwt_with_payload(&serde_json::json!({ "exp": 42 }));
+        assert_eq!(parse_exp_secs(&format!("Bearer {token}")), Some(42));
+    }
+
+    #[test]
+    fn none_for_missing_exp_or_non_jwt() {
+        assert_eq!(
+            parse_exp_secs(&jwt_with_payload(&serde_json::json!({ "sub": "x" }))),
+            None
+        );
+        assert_eq!(parse_exp_secs("not-a-jwt"), None);
+        assert_eq!(parse_exp_secs(""), None);
+    }
+}
@@ -22,6 +22,7 @@ pub mod gpu;
 pub mod grpc_client;
 pub mod image;
 pub mod inference;
+pub mod jwt;
 pub mod metadata;
 pub mod net;
 pub mod paths;
 
@@ -0,0 +1,37 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+[package]
+name = "openshell-sdk"
+description = "Shared async Rust client for OpenShell gateways"
+version.workspace = true
+edition.workspace = true
+rust-version.workspace = true
+license.workspace = true
+repository.workspace = true
+
+[dependencies]
+openshell-core = { path = "../openshell-core" }
+async-trait = "0.1"
+futures = { workspace = true }
+hyper = { workspace = true }
+hyper-util = { workspace = true }
+miette = { workspace = true }
+oauth2 = "5"
+reqwest = { workspace = true }
+rustls = { workspace = true }
+serde = { workspace = true }
+thiserror = { workspace = true }
+tokio = { workspace = true }
+tokio-rustls = { workspace = true }
+tokio-tungstenite = { workspace = true }
+tonic = { workspace = true, features = ["tls-native-roots"] }
+tower = { workspace = true }
+tracing = { workspace = true }
+
+[dev-dependencies]
+tokio = { workspace = true, features = ["macros", "rt-multi-thread"] }
+tokio-stream = { workspace = true }
+
+[lints]
+workspace = true
@@ -0,0 +1,69 @@
+# openshell-sdk
+
+`openshell-sdk` is the shared async Rust client for OpenShell gateways. It owns
+gRPC channel setup, TLS, OIDC refresh, and the Cloudflare Access tunnel so the
+CLI, the TUI, and language bindings share one client implementation. Callers
+pass an explicit bearer token; the SDK does no filesystem access and no
+gateway-name resolution.
+
+## Two layers
+
+- `OpenShellClient` — the curated, sandbox-focused surface: health, sandbox
+  CRUD, readiness/deletion waits, and non-streaming exec.
+- `raw` — direct access to the generated tonic clients for RPCs the curated
+  surface doesn't yet cover (inference, providers, policy, logs, settings, SSH,
+  forwarding).
+
+## Auth and refresh
+
+The curated surface drives OIDC refresh automatically: proactively before a
+request and reactively on `Unauthenticated`. Refreshes are single-flight, so
+only one is in flight at a time.
+
+The plain `raw_grpc`/`raw_inference` accessors do not refresh; they return a
+client bound to the current token. When a refresher is wired, use
+`raw_grpc_fresh`/`raw_inference_fresh` to refresh before the call, and
+`force_refresh` to recover after a raw RPC returns `Unauthenticated`.
+
+The SDK consumes a `Refresh` trait that the caller implements; it does not run
+the OIDC browser flow itself.
+
+## Transport modes
+
+- Plaintext (local development)
+- Server-authenticated TLS (system roots, or a pinned private CA via `ca_cert`)
+- OIDC bearer over HTTPS (gateways behind an OAuth2/OIDC IdP)
+- Cloudflare Access tunnel (hosted gateways)
+- Insecure TLS (development/debug; certificate verification disabled)
+
+mTLS (client certificates) is not supported.
+
+## Public surface
+
+`OpenShellClient::connect(ClientConfig)` returns a connected client exposing
+`health`, `create_sandbox`, `get_sandbox`, `list_sandboxes`, `delete_sandbox`,
+`wait_ready`, `wait_deleted`, and `exec`. Curated types (`SandboxSpec`,
+`SandboxRef`, `Health`, `ListOptions`, `ExecOptions`, `SandboxPhase`) use
+SDK-shaped enums rather than raw proto integers. Failures map to a typed
+`SdkError` with a discriminable kind.
+
+## Modules
+
+| Module | Purpose |
+|---|---|
+| `client` | High-level `OpenShellClient` and the curated sandbox surface. |
+| `config` | `ClientConfig`, `AuthConfig`. |
+| `transport` | Channel construction, TLS resolution, request interceptors. |
+| `auth` | `EdgeAuthInterceptor` for bearer-token attachment. |
+| `oidc` | OIDC token handling at the transport layer. |
+| `refresh` | `Refresh` trait and single-flight refresh coalescing. |
+| `edge_tunnel` | Cloudflare Access tunnel dialer. |
+| `error` | `SdkError` taxonomy. |
+| `types` | Curated request/response types and proto conversions. |
+| `raw` | Escape hatch re-exporting the generated tonic clients. |
+
+## Notes
+
+- Async-only. Tonic is async-native; callers needing a blocking call can wrap
+  with their own runtime.
+- The curated surface will grow as more RPCs graduate from `raw`.
@@ -0,0 +1,112 @@
+// SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+//! Bearer-token authentication interceptor for outgoing gRPC requests.
+
+use crate::error::{Result, SdkError};
+use std::sync::{Arc, RwLock};
+use tonic::metadata::{Ascii, MetadataValue};
+
+/// Shared, mutable OIDC bearer header.
+///
+/// The interceptor reads it on every request and a [`crate::TokenSource`]
+/// overwrites it in place on refresh, so rotation propagates to an
+/// already-connected client without rebuilding the channel. Mirrors the slot
+/// pattern in `openshell-core`'s gRPC client.
+pub type BearerSlot = Arc<RwLock<Option<MetadataValue<Ascii>>>>;
+
+/// Build the `authorization` header value for an OIDC bearer token.
+pub fn bearer_metadata(token: &str) -> Result<MetadataValue<Ascii>> {
+    format!("Bearer {token}")
+        .parse()
+        .map_err(|_| SdkError::auth("invalid OIDC token value"))
+}
+
+/// Interceptor that injects authentication headers into every outgoing gRPC request.
+///
+/// Supports OIDC Bearer tokens (standard `authorization` header) and
+/// Cloudflare Access tokens (custom headers). When no token is set, acts
+/// as a no-op. OIDC takes precedence over edge tokens.
+///
+/// The OIDC bearer is held in a shared [`BearerSlot`] so token refresh can
+/// update it live; edge tokens are captured once at construction (the edge
+/// tunnel binds the credential at handshake time).
+#[derive(Clone)]
+pub struct EdgeAuthInterceptor {
+    bearer: Option<BearerSlot>,
+    header_value: Option<MetadataValue<Ascii>>,
+    cookie_value: Option<MetadataValue<Ascii>>,
+}
+
+impl EdgeAuthInterceptor {
+    /// Create an interceptor from optional token strings.
+    ///
+    /// OIDC bearer token takes precedence over edge token. Returns a no-op
+    /// interceptor when neither token is provided.
+    pub fn new(oidc_token: Option<&str>, edge_token: Option<&str>) -> Result<Self> {
+        if let Some(token) = oidc_token {
+            let bearer = bearer_metadata(token)?;
+            return Ok(Self {
+                bearer: Some(Arc::new(RwLock::new(Some(bearer)))),
+                header_value: None,
+                cookie_value: None,
+            });
+        }
+
+        let (header_value, cookie_value) = match edge_token {
+            Some(t) => {
+                let hv: MetadataValue<Ascii> = t
+                    .parse()
+                    .map_err(|_| SdkError::auth("invalid edge token value"))?;
+                let cv: MetadataValue<Ascii> = format!("CF_Authorization={t}")
+                    .parse()
+                    .map_err(|_| SdkError::auth("invalid edge token value for cookie"))?;
+                (Some(hv), Some(cv))
+            }
+            None => (None, None),
+        };
+        Ok(Self {
+            bearer: None,
+            header_value,
+            cookie_value,
+        })
+    }
+
+    /// No-op interceptor that passes requests through without modification.
+    pub fn noop() -> Self {
+        Self {
+            bearer: None,
+            header_value: None,
+            cookie_value: None,
+        }
+    }
+
+    /// Handle to the live OIDC bearer slot, if this interceptor carries one.
+    ///
+    /// The high-level client uses this to overwrite the token in place after
+    /// a refresh. `None` for edge-token and no-op interceptors.
+    pub fn bearer_slot(&self) -> Option<BearerSlot> {
+        self.bearer.clone()
+    }
+}
+
+impl tonic::service::Interceptor for EdgeAuthInterceptor {
+    fn call(
+        &mut self,
+        mut req: tonic::Request<()>,
+    ) -> std::result::Result<tonic::Request<()>, tonic::Status> {
+        if let Some(slot) = &self.bearer
+            && let Some(val) = slot.read().ok().and_then(|g| g.clone())
+        {
+            req.metadata_mut().insert("authorization", val);
+        }
+        if let Some(ref val) = self.header_value {
+            req.metadata_mut()
+                .insert("cf-access-jwt-assertion", val.clone());
+        }
+        if let Some(ref val) = self.cookie_value {
+            req.metadata_mut().insert("cookie", val.clone());
+        }
+        Ok(req)
+    }
+}