From ce07e00a94de4d5c1bc5081356f3005d22423b95 Mon Sep 17 00:00:00 2001 From: Robby Cochran Date: Fri, 21 Aug 2026 21:49:19 -0400 Subject: [PATCH] docs(sdkclient): drop build-ladder references from comments Rewrite comments that referenced the implementation plan (slice numbers S1/S3/S4, "has landed", "see specs findings", TODO(PR8), "kill-gate") into durable form. The real maintenance facts are preserved: the SA-OIDC dial path is untested end-to-end because no OIDC gateway is available in this environment, and the E2E health test proves mTLS Health from within the module against a live gateway. Comment-only; no behavior change. --- internal/openshell/sdkclient/auth.go | 3 ++- internal/openshell/sdkclient/client.go | 20 +++++++++---------- .../openshell/sdkclient/health_e2e_test.go | 6 +++--- 3 files changed, 15 insertions(+), 14 deletions(-) diff --git a/internal/openshell/sdkclient/auth.go b/internal/openshell/sdkclient/auth.go index 3379e5e..1ac93bf 100644 --- a/internal/openshell/sdkclient/auth.go +++ b/internal/openshell/sdkclient/auth.go @@ -66,7 +66,8 @@ func planConnection(cfg *gw.Config, env EnvLookup) (connPlan, error) { plan.branch = branchDefault plan.tls = nil } else { - // TODO(PR8): audience/scopes unverified — needs OIDC gateway + // Service-account client-credentials. The live dial is untested — + // no OIDC gateway is available to verify audience/scopes against. plan.branch = branchSAOIDC plan.tls = nil } diff --git a/internal/openshell/sdkclient/client.go b/internal/openshell/sdkclient/client.go index 1e640e5..49f385d 100644 --- a/internal/openshell/sdkclient/client.go +++ b/internal/openshell/sdkclient/client.go @@ -2,9 +2,9 @@ // OpenShell Go SDK. It translates between the harness-owned internal/openshell // vocabulary and the SDK, keeping every SDK type behind the firewall. // -// S3 has landed: translate (errors.go) and provider mapping (provider.go) are -// in place, and dial covers all branches (mTLS verified against a live gateway; -// default and SA-OIDC selected and compiled but unverified). +// It dials via mTLS, an unauthenticated default, and service-account OIDC. The +// mTLS path is verified against a live gateway; the SA-OIDC path is untested +// end-to-end (no OIDC gateway is available in this environment). package sdkclient import ( @@ -42,8 +42,8 @@ type client struct { // New constructs an openshell.Client for the given target: it loads the // CLI-managed gateway config, resolves the dial plan via planConnection, and // executes it via dial. Only the mTLS branch is verified against a live -// gateway; the default and SA-OIDC branches compile and are selected but the -// SA-OIDC path is UNVERIFIED (no OIDC gateway available). +// gateway; the SA-OIDC branch is untested end-to-end (no OIDC gateway +// available). func New(ctx context.Context, t openshell.Target) (openshell.Client, error) { cfg, err := gateway.LoadConfig(t.Gateway) if err != nil { @@ -69,7 +69,7 @@ func New(ctx context.Context, t openshell.Target) (openshell.Client, error) { } // NewFromClient wraps an existing SDK client (or the SDK fake) bound to a -// workspace. It is the injection seam used by white-box tests and, in S4, by +// workspace. It is the injection seam used by white-box tests and by // internal/testutil. Empty workspace defaults to defaultWorkspace. func NewFromClient(raw v1.ClientInterface, workspace string) openshell.Client { if workspace == "" { @@ -136,10 +136,10 @@ func clientCredentials(ctx context.Context, p connPlan) (*oauth2.Token, error) { // deadline, every grant — eager and refresh — gets its own bounded // oidcGrantTimeout so a stalled token endpoint can never block indefinitely. // -// UNVERIFIED (no OIDC gateway; see specs findings): this path is exercised only -// for branch selection and compilation. TODO(PR8): audience/scopes unverified — -// needs an OIDC gateway. On any failure it returns a wrapped sentinel, never -// panics, and never places the client secret into an error message. +// Untested end-to-end: no OIDC gateway is available in this environment, so +// this path is exercised only for branch selection and compilation, and its +// audience/scopes are unverified. On any failure it returns a wrapped sentinel, +// never panics, and never places the client secret into an error message. func dialSAOIDC(ctx context.Context, p connPlan) (v1.ClientInterface, error) { eagerCtx, cancel := context.WithTimeout(ctx, oidcGrantTimeout) defer cancel() diff --git a/internal/openshell/sdkclient/health_e2e_test.go b/internal/openshell/sdkclient/health_e2e_test.go index 4ce5412..8e5d33b 100644 --- a/internal/openshell/sdkclient/health_e2e_test.go +++ b/internal/openshell/sdkclient/health_e2e_test.go @@ -10,8 +10,8 @@ import ( "github.com/stackrox/harness-openshell/internal/openshell/sdkclient" ) -// TestHealthE2E is the S1 kill-gate: it proves an mTLS Health().Check succeeds -// from within the harness module (not a /tmp spike) against a real gateway. +// TestHealthE2E proves an mTLS Health().Check succeeds from within the harness +// module against a real gateway. // // It is skipped unless HARNESS_E2E_GATEWAY names a registered openshell gateway // (the local mTLS dev gateway is "openshell"). Optional HARNESS_E2E_WORKSPACE @@ -21,7 +21,7 @@ import ( func TestHealthE2E(t *testing.T) { gw := os.Getenv("HARNESS_E2E_GATEWAY") if gw == "" { - t.Skip("set HARNESS_E2E_GATEWAY to a registered mTLS gateway to run the S1 kill-gate") + t.Skip("set HARNESS_E2E_GATEWAY to a registered mTLS gateway to run this end-to-end check") } ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)