fix(sdk/go): harden Go SDK from deep review findings

Security: replace http.DefaultClient with 30s-timeout oidcHTTPClient
across all 5 OIDC call sites, add sync.Once to callback server result
delivery, validate URL scheme before browser exec (Windows cmd.exe
injection prevention), add io.LimitReader (1 MiB) to all unbounded
io.ReadAll sites.

Correctness: fix interactiveSession goroutine leak (add context
cancellation to Close), clone globalRevisions before in-place sort
(data race), add FailedPrecondition/ResourceExhausted/OutOfRange to
gRPC error mapping with Cause preservation, add ErrTransportNotAvailable
for file client transport gating, propagate structpb conversion errors
through SandboxPolicyToProto.

Validation: add negative ListOptions checks to sandbox and provider
clients, add FR-007 validation parity (sandboxName/remotePath) to 7
fake client methods across 4 files, deep-copy NetworkMiddlewares and
L7 Params/Mcp fields in fake sandbox policy.

Tests: add mutex to 4 sandbox mock handlers, strengthen exec/file test
assertions, verify all 12 sub-client accessors, fix watch stop
idempotency test.

Docs: add "default" workspace argument to 80+ SDK calls across 16
documentation files, add MITM warning to TLSConfig.Insecure godoc.

Signed-off-by: Roland Huß <rhuss@redhat.com>

Author: rhuss

mise.lock

@@ -52,19 +52,19 @@ if err != nil {
 defer client.Close()
 
 // Create a sandbox and wait until it's ready
-sandbox, err := client.Sandboxes().Create(ctx, "my-sandbox", &v1.SandboxSpec{
+sandbox, err := client.Sandboxes().Create(ctx, "default", "my-sandbox", &v1.SandboxSpec{
     Template: &v1.SandboxTemplate{Image: "python:3.12"},
 }, nil)
 if err != nil {
     log.Fatal(err)
 }
-sandbox, err = client.Sandboxes().WaitReady(ctx, sandbox.Name)
+sandbox, err = client.Sandboxes().WaitReady(ctx, "default", sandbox.Name)
 if err != nil {
     log.Fatal(err)
 }
 
 // Run a command
-result, err := client.Exec().Run(ctx, sandbox.Name,
+result, err := client.Exec().Run(ctx, "default", sandbox.Name,
     []string{"python3", "-c", "print('hello from sandbox')"},
     v1.ExecOptions{},
 )
@@ -192,6 +192,21 @@ See the [oidc package docs](https://pkg.go.dev/github.com/NVIDIA/OpenShell/sdk/g
 
 See the [Getting Started](https://ro14nd.de/openshell-sdk-go/getting-started.html) guide for the full walkthrough.
 
+## Migrating from v0.0.101
+
+The pre-1.0 SDK intentionally includes source-incompatible API corrections:
+
+- `TCP.Listen` returns a `ForwardListener` lifecycle handle. The SDK owns the
+  accept loop; callers dial `Addr()` and call `Close()` instead of calling
+  `Accept()` or passing the handle to `http.Serve`.
+- Resource operations take an explicit workspace, and workspace-bearing domain
+  types preserve that scope.
+- Several public struct field orders changed. Use keyed struct literals.
+- Initialisms use Go spelling, including `JSONRPCMaxBodyBytes`.
+
+These changes are intentional while the module remains below v1. Update callers
+as one migration rather than relying on the v0.0.101 API shape.
+
 ### Inference Route Management
 
 Configure how inference requests are routed for a workspace:
@@ -253,7 +268,7 @@ consumers import a single package. See the [Architecture](https://ro14nd.de/open
 | Provider profiles (list, import, lint, update) | `ProfileInterface` | [Profiles](https://ro14nd.de/openshell-sdk-go/api/profiles.html) |
 | Credential refresh (configure, rotate, status) | `RefreshInterface` | [Refresh](https://ro14nd.de/openshell-sdk-go/api/refresh.html) |
 | Service exposure (expose, list, delete) | `ServiceInterface` | [Services](https://ro14nd.de/openshell-sdk-go/api/services.html) |
-| File transfer (upload, download) | `FileInterface` | [Files](https://ro14nd.de/openshell-sdk-go/api/files.html) |
+| File transfer API (transport capability-gated) | `FileInterface` | [Files](https://ro14nd.de/openshell-sdk-go/api/files.html) |
 | Policy management (draft review, approve, reject, merge, global policy) | `PolicyInterface` | [Policy](https://ro14nd.de/openshell-sdk-go/api/policy.html) |
 | Sandbox logs (streaming retrieval) | `SandboxInterface` | [Sandboxes](https://ro14nd.de/openshell-sdk-go/api/sandboxes.html) |
 | Workspace management (create, get, list, delete, members) | `WorkspaceInterface` | [Workspaces](https://ro14nd.de/openshell-sdk-go/api/workspaces.html) |

sdk/go/README.md

@@ -3,22 +3,19 @@
 
 # Code generation for the Go SDK. buf compiles the proto module with its own
 # compiler and runs protoc-gen-go / protoc-gen-go-grpc from mise-managed
-# binaries. Limited to the client-surface closure (openshell, datamodel,
-# sandbox, options, inference).
+# binaries. The public SDK entry points are declared here; imported schemas
+# are included automatically, so their canonical dependency closure is
+# generated without duplicating a filename list in the generation scripts.
 version: v2
 
 inputs:
-  - directory: proto
-    paths:
-      - proto/openshell.proto
-      - proto/datamodel.proto
-      - proto/sandbox.proto
-      - proto/options.proto
-      - proto/inference.proto
+  - proto_file: proto/openshell.proto
+  - proto_file: proto/inference.proto
 
 plugins:
   - local: protoc-gen-go
-    out: .
+    out: sdk/go
+    include_imports: true
     opt:
       - module=github.com/NVIDIA/OpenShell/sdk/go
       - Mopenshell.proto=github.com/NVIDIA/OpenShell/sdk/go/proto/openshellv1
@@ -27,7 +24,8 @@ plugins:
       - Moptions.proto=github.com/NVIDIA/OpenShell/sdk/go/proto/optionsv1
       - Minference.proto=github.com/NVIDIA/OpenShell/sdk/go/proto/inferencev1
   - local: protoc-gen-go-grpc
-    out: .
+    out: sdk/go
+    include_imports: true
     opt:
       - module=github.com/NVIDIA/OpenShell/sdk/go
       - Mopenshell.proto=github.com/NVIDIA/OpenShell/sdk/go/proto/openshellv1

sdk/go/buf.gen.yaml

@@ -9,7 +9,7 @@ Retrieve and update configuration for sandboxes and the gateway.
 Retrieve the current configuration for a specific sandbox.
 
 ```go
-config, err := client.Config().GetSandbox(ctx, "sandbox-123")
+config, err := client.Config().GetSandbox(ctx, "default", "sandbox-123")
 if err != nil {
     log.Fatal(err)
 }
@@ -34,7 +34,7 @@ fmt.Printf("Gateway settings revision: %d\n", config.SettingsRevision)
 Apply a configuration update. The update is validated before being applied.
 
 ```go
-result, err := client.Config().Update(ctx, &v1.ConfigUpdate{
+result, err := client.Config().Update(ctx, "default", &v1.ConfigUpdate{
     Name:       "sandbox-123",
     SettingKey:  "idle_timeout",
     SettingValue: &v1.SettingValue{

sdk/go/buf.yaml

@@ -10,7 +10,7 @@ Execute commands in a sandbox with three modes: one-shot (`Run`), streaming
 Execute a command and collect all output into a single result.
 
 ```go
-result, err := client.Exec().Run(ctx, "sbx-123", []string{"ls", "-la"})
+result, err := client.Exec().Run(ctx, "default", "sbx-123", []string{"ls", "-la"})
 if err != nil {
     log.Fatal(err)
 }
@@ -35,7 +35,7 @@ The SDK collects all streamed events, assembles stdout/stderr, and returns a sin
 Execute a command and process output chunks as they arrive.
 
 ```go
-stream, err := client.Exec().Stream(ctx, "sbx-123", []string{"tail", "-f", "/var/log/app.log"})
+stream, err := client.Exec().Stream(ctx, "default", "sbx-123", []string{"tail", "-f", "/var/log/app.log"})
 if err != nil {
     log.Fatal(err)
 }
@@ -67,7 +67,7 @@ fmt.Println("Exited with:", exitCode)
 Open a bidirectional terminal session with a command.
 
 ```go
-session, err := client.Exec().Interactive(ctx, "sbx-123", []string{"/bin/bash"}, 80, 24)
+session, err := client.Exec().Interactive(ctx, "default", "sbx-123", []string{"/bin/bash"}, 80, 24)
 if err != nil {
     log.Fatal(err)
 }

sdk/go/docs/src/api/config.md

@@ -2,33 +2,35 @@
 
 Accessor: `client.Files()`
 
-Upload and download files to and from sandboxes. Uses gRPC streaming for efficient
-transfer of large files.
+`FileInterface` reserves the upload and download API while keeping sandbox lookup
+and SSH-session lifecycle behavior stable. The standalone SDK does not currently
+ship an SSH file-transfer transport, so both operations return
+`v1.ErrTransportNotAvailable` before performing local validation or gateway RPCs.
 
 ## Upload
 
-Upload a file from the local filesystem to a path inside a sandbox.
-The file is streamed in chunks using client-side gRPC streaming.
+Detect transport availability programmatically:
 
 ```go
-err := client.Files().Upload(ctx, "sandbox-123", "./data/config.yaml", "/app/config.yaml")
-if err != nil {
+err := client.Files().Upload(ctx, "default", "sandbox-123", "./data/config.yaml", "/app/config.yaml")
+if errors.Is(err, v1.ErrTransportNotAvailable) {
+    // Use another transfer mechanism until an SSH transport is available.
+} else if err != nil {
     log.Fatal(err)
 }
-fmt.Println("File uploaded successfully")
 ```
 
 ## Download
 
-Download a file from a sandbox to the local filesystem.
-The file is received in chunks using server-side gRPC streaming.
+`Download` has the same capability gate:
 
 ```go
-err := client.Files().Download(ctx, "sandbox-123", "/app/output.log", "./output.log")
-if err != nil {
+err := client.Files().Download(ctx, "default", "sandbox-123", "/app/output.log", "./output.log")
+if errors.Is(err, v1.ErrTransportNotAvailable) {
+    // Use another transfer mechanism until an SSH transport is available.
+} else if err != nil {
     log.Fatal(err)
 }
-fmt.Println("File downloaded successfully")
 ```
 
 See also: [Error Handling](../error-handling.md), [Testing](../testing.md)

sdk/go/docs/src/api/exec.md

@@ -10,7 +10,7 @@ go through a draft, review, and approval cycle before being applied.
 Retrieve the current draft policy for a sandbox.
 
 ```go
-draft, err := client.Policy().GetDraft(ctx, "my-sandbox")
+draft, err := client.Policy().GetDraft(ctx, "default", "my-sandbox")
 if err != nil {
     log.Fatal(err)
 }
@@ -25,7 +25,7 @@ for _, chunk := range draft.Chunks {
 Approve all pending chunks in a single operation.
 
 ```go
-result, err := client.Policy().ApproveAllDraftChunks(ctx, "my-sandbox")
+result, err := client.Policy().ApproveAllDraftChunks(ctx, "default", "my-sandbox")
 if err != nil {
     log.Fatal(err)
 }
@@ -38,7 +38,7 @@ fmt.Printf("Approved %d chunks (skipped %d), policy version: %d\n",
 Check the current policy enforcement status for a sandbox.
 
 ```go
-status, err := client.Policy().GetStatus(ctx, "my-sandbox")
+status, err := client.Policy().GetStatus(ctx, "default", "my-sandbox")
 if err != nil {
     log.Fatal(err)
 }
@@ -51,7 +51,7 @@ fmt.Printf("Active version: %d, revision status: %s\n",
 List all policy revisions for a sandbox.
 
 ```go
-revisions, err := client.Policy().List(ctx, "my-sandbox")
+revisions, err := client.Policy().List(ctx, "default", "my-sandbox")
 if err != nil {
     log.Fatal(err)
 }
@@ -66,7 +66,7 @@ for _, rev := range revisions {
 Reject a specific draft chunk, providing a reason.
 
 ```go
-err := client.Policy().RejectDraftChunk(ctx, "my-sandbox", "chunk-abc", "Too permissive")
+err := client.Policy().RejectDraftChunk(ctx, "default", "my-sandbox", "chunk-abc", "Too permissive")
 if err != nil {
     log.Fatal(err)
 }
@@ -77,7 +77,7 @@ if err != nil {
 Modify the proposed rule in a draft chunk before approval.
 
 ```go
-err := client.Policy().EditDraftChunk(ctx, "my-sandbox", "chunk-abc", &v1.NetworkPolicyRule{
+err := client.Policy().EditDraftChunk(ctx, "default", "my-sandbox", "chunk-abc", &v1.NetworkPolicyRule{
     Name: "allow-api",
     Endpoints: []v1.PolicyNetworkEndpoint{{
         Host:     "api.example.com",

sdk/go/docs/src/api/files.md

@@ -10,7 +10,7 @@ credentials, and model mappings for providers like OpenAI, Anthropic, or custom
 List all provider profiles visible to the current user.
 
 ```go
-profiles, err := client.Providers().Profiles().List(ctx)
+profiles, err := client.Providers().Profiles().List(ctx, "default")
 if err != nil {
     log.Fatal(err)
 }
@@ -24,7 +24,7 @@ for _, p := range profiles {
 Import one or more provider profiles from configuration items.
 
 ```go
-result, err := client.Providers().Profiles().Import(ctx, []v1.ProfileImportItem{
+result, err := client.Providers().Profiles().Import(ctx, "default", []v1.ProfileImportItem{
     {
         Profile: v1.ProviderProfile{
             DisplayName: "OpenAI",
@@ -44,14 +44,14 @@ fmt.Printf("Imported: %v\n", result.Imported)
 Update a profile using optimistic concurrency control via the resource version.
 
 ```go
-profile, err := client.Providers().Profiles().Get(ctx, "profile-id")
+profile, err := client.Providers().Profiles().Get(ctx, "default", "profile-id")
 if err != nil {
     log.Fatal(err)
 }
 
 profile.DisplayName = "Updated Provider"
 result, err := client.Providers().Profiles().Update(
-    ctx,
+    ctx, "default",
     profile.ID,
     profile.ResourceVersion,
     v1.ProfileImportItem{Profile: *profile, Source: "manual"},
@@ -73,7 +73,7 @@ items := []v1.ProfileImportItem{
         Source:  "manual",
     },
 }
-result, err := client.Providers().Profiles().Lint(ctx, items)
+result, err := client.Providers().Profiles().Lint(ctx, "default", items)
 if err != nil {
     log.Fatal(err)
 }