+
+
diff --git a/internal/webui/desktop.go b/internal/webui/desktop.go
new file mode 100644
index 0000000..e9469a0
--- /dev/null
+++ b/internal/webui/desktop.go
@@ -0,0 +1,102 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package webui
+
+import (
+ "net/http"
+ "sync"
+)
+
+// LocalHandler is a same-process HTTP request handler. It exists so a native
+// WebView can reuse the hardened web UI without opening a TCP listener.
+type LocalHandler interface {
+ ServeHTTP(http.ResponseWriter, *http.Request)
+}
+
+// InProcessHandler routes requests to the active local UI session. A replaced
+// session remains leased only by requests that selected it before the swap.
+type InProcessHandler struct {
+ mu sync.Mutex
+ current *inProcessSession
+}
+
+type inProcessSession struct {
+ handler LocalHandler
+ active uint64
+ retired bool
+ drained chan struct{}
+}
+
+// NewInProcessHandler constructs a handler whose active UI session can be
+// replaced without starting a network listener.
+func NewInProcessHandler(initial LocalHandler) *InProcessHandler {
+ handler := &InProcessHandler{}
+ if initial != nil {
+ handler.current = newInProcessSession(initial)
+ }
+ return handler
+}
+
+func (handler *InProcessHandler) ServeHTTP(response http.ResponseWriter, request *http.Request) {
+ session := handler.acquire()
+ if session == nil {
+ http.Error(response, "local desktop is shutting down", http.StatusServiceUnavailable)
+ return
+ }
+ defer handler.release(session)
+ session.handler.ServeHTTP(response, request)
+}
+
+// Replace atomically selects the next local UI session. It returns a channel
+// that closes once requests leased to the previous session have drained. A nil
+// handler makes future requests fail closed without blocking new requests on an
+// old, slow operation.
+func (handler *InProcessHandler) Replace(next LocalHandler) <-chan struct{} {
+ handler.mu.Lock()
+ previous := handler.current
+ if next == nil {
+ handler.current = nil
+ } else {
+ handler.current = newInProcessSession(next)
+ }
+ if previous == nil {
+ handler.mu.Unlock()
+ return nil
+ }
+ previous.retired = true
+ if previous.active == 0 {
+ close(previous.drained)
+ }
+ drained := previous.drained
+ handler.mu.Unlock()
+ return drained
+}
+
+func newInProcessSession(next LocalHandler) *inProcessSession {
+ return &inProcessSession{handler: next, drained: make(chan struct{})}
+}
+
+func (handler *InProcessHandler) acquire() *inProcessSession {
+ handler.mu.Lock()
+ defer handler.mu.Unlock()
+ if handler.current == nil {
+ return nil
+ }
+ handler.current.active++
+ return handler.current
+}
+
+func (handler *InProcessHandler) release(session *inProcessSession) {
+ handler.mu.Lock()
+ defer handler.mu.Unlock()
+ session.active--
+ if session.retired && session.active == 0 {
+ close(session.drained)
+ }
+}
+
+// InProcessMiddleware adapts a local handler to Wails without using the
+// framework default asset route or opening a listener.
+func InProcessMiddleware(handler LocalHandler) func(http.Handler) http.Handler {
+ return func(http.Handler) http.Handler { return handler }
+}
diff --git a/internal/webui/desktop_test.go b/internal/webui/desktop_test.go
new file mode 100644
index 0000000..77a237f
--- /dev/null
+++ b/internal/webui/desktop_test.go
@@ -0,0 +1,62 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package webui
+
+import (
+ "net/http"
+ "net/http/httptest"
+ "testing"
+ "time"
+)
+
+type blockingLocalHandler struct {
+ started chan<- struct{}
+ release <-chan struct{}
+}
+
+func (handler blockingLocalHandler) ServeHTTP(response http.ResponseWriter, _ *http.Request) {
+ close(handler.started)
+ <-handler.release
+ response.WriteHeader(http.StatusNoContent)
+}
+
+func TestInProcessHandlerReplacesWithoutBlockingNewRequests(t *testing.T) {
+ t.Parallel()
+ started := make(chan struct{})
+ release := make(chan struct{})
+ handler := NewInProcessHandler(blockingLocalHandler{started: started, release: release})
+ served := make(chan struct{})
+ go func() {
+ handler.ServeHTTP(httptest.NewRecorder(), httptest.NewRequest(http.MethodGet, "wails://wails/", nil))
+ close(served)
+ }()
+ select {
+ case <-started:
+ case <-time.After(time.Second):
+ t.Fatal("initial in-process request did not start")
+ }
+ drained := handler.Replace(http.HandlerFunc(func(response http.ResponseWriter, _ *http.Request) {
+ response.WriteHeader(http.StatusNoContent)
+ }))
+ select {
+ case <-drained:
+ t.Fatal("previous session drained while its request was in flight")
+ case <-time.After(20 * time.Millisecond):
+ }
+ fresh := httptest.NewRecorder()
+ handler.ServeHTTP(fresh, httptest.NewRequest(http.MethodGet, "wails://wails/", nil))
+ if fresh.Code != http.StatusNoContent {
+ t.Fatalf("replacement handler status = %d, want %d", fresh.Code, http.StatusNoContent)
+ }
+ close(release)
+ select {
+ case <-served:
+ case <-time.After(time.Second):
+ t.Fatal("initial in-process request did not finish")
+ }
+ select {
+ case <-drained:
+ case <-time.After(time.Second):
+ t.Fatal("previous session did not drain after its request completed")
+ }
+}
diff --git a/internal/webui/server.go b/internal/webui/server.go
index 1919108..f2faaf2 100644
--- a/internal/webui/server.go
+++ b/internal/webui/server.go
@@ -27,6 +27,10 @@ import (
const (
csrfHeader = "X-Sith-CSRF"
localMode = "local"
+
+ // DesktopOrigin is Wails' in-process macOS WebView origin. It never binds a
+ // TCP listener and is accepted only by the native desktop host.
+ DesktopOrigin = "wails://wails"
)
//go:embed assets/*
@@ -85,11 +89,16 @@ func New(ctx context.Context, store *fleetcache.Store, syncer Syncer, local loca
}, nil
}
-// Handler returns the hardened frontend/API handler for one exact listener URL.
+// Handler returns the hardened frontend/API handler for one exact local origin.
func (application *Application) Handler(baseURL string) (http.Handler, error) {
parsed, err := url.Parse(baseURL)
- if err != nil || parsed.Scheme != "http" || parsed.Host == "" || parsed.Path != "" {
- return nil, fmt.Errorf("configure web UI handler: base URL must be an http origin")
+ if err != nil || parsed.Host == "" || parsed.Path != "" || parsed.RawQuery != "" || parsed.Fragment != "" {
+ return nil, fmt.Errorf("configure web UI handler: base URL must be an exact local origin")
+ }
+ if baseURL != DesktopOrigin {
+ if parsed.Scheme != "http" || ValidateLoopbackAddress(parsed.Hostname()) != nil {
+ return nil, fmt.Errorf("configure web UI handler: base URL must be a loopback http origin")
+ }
}
mux := http.NewServeMux()
mux.HandleFunc("GET /", application.serveIndex)
diff --git a/internal/webui/server_test.go b/internal/webui/server_test.go
index 3427e42..77517ce 100644
--- a/internal/webui/server_test.go
+++ b/internal/webui/server_test.go
@@ -7,6 +7,7 @@ import (
"encoding/json"
"fmt"
"io"
+ "io/fs"
"net/http"
"net/http/httptest"
"slices"
@@ -88,6 +89,54 @@ func TestHandlerEnforcesHostOriginCapabilityAndSecurityHeaders(t *testing.T) {
}
}
+func TestHandlerAllowsOnlyTheExplicitDesktopOrigin(t *testing.T) {
+ t.Parallel()
+ application := testApplication(t)
+ handler, err := application.Handler(DesktopOrigin)
+ if err != nil {
+ t.Fatalf("Handler(%q) error = %v", DesktopOrigin, err)
+ }
+ request := httptest.NewRequest(http.MethodGet, DesktopOrigin+"/api/v1/meta", nil)
+ request.Host = "wails"
+ request.Header.Set(csrfHeader, application.token)
+ request.Header.Set("Origin", DesktopOrigin)
+ recorder := httptest.NewRecorder()
+ handler.ServeHTTP(recorder, request)
+ if recorder.Code != http.StatusOK {
+ t.Fatalf("desktop meta status/body = %d/%s", recorder.Code, recorder.Body.String())
+ }
+ for _, origin := range []string{"https://wails.localhost", "http://example.com", "wails://attacker"} {
+ if _, err := application.Handler(origin); err == nil {
+ t.Errorf("Handler(%q) error = nil", origin)
+ }
+ }
+}
+
+func TestDesktopFolderBridgeIsOptInAndDoesNotExposePaths(t *testing.T) {
+ t.Parallel()
+ index, err := fs.ReadFile(embeddedAssets, "assets/index.html")
+ if err != nil {
+ t.Fatal(err)
+ }
+ script, err := fs.ReadFile(embeddedAssets, "assets/app.js")
+ if err != nil {
+ t.Fatal(err)
+ }
+ if !strings.Contains(string(index), `id="import-folder-button" class="quiet-action" type="button" hidden`) {
+ t.Fatal("desktop import control is not hidden by default")
+ }
+ if !strings.Contains(string(script), "window.go?.cli?.DesktopBridge?.ChooseKubeconfigDirectory") ||
+ !strings.Contains(string(script), "if (await directoryPicker()) window.location.reload()") {
+ t.Fatal("desktop bridge is not opt-in or does not reload after a successful source swap")
+ }
+ if !strings.Contains(string(script), `snapshot.last_error === desktopHydrationFailure`) {
+ t.Fatal("desktop UI does not allowlist a sanitized hydration failure")
+ }
+ if strings.Contains(string(script), "selectedDirectory") || strings.Contains(string(script), "kubeconfigDir") {
+ t.Fatal("desktop bridge must not retain a selected local path in the UI")
+ }
+}
+
func TestSnapshotReadsCacheOnlyAndRefreshIsExplicit(t *testing.T) {
t.Parallel()
syncer := &webSyncer{}
diff --git a/sessions/2026-07-14-f11-native-desktop-shell.md b/sessions/2026-07-14-f11-native-desktop-shell.md
new file mode 100644
index 0000000..64d248c
--- /dev/null
+++ b/sessions/2026-07-14-f11-native-desktop-shell.md
@@ -0,0 +1,104 @@
+# F11.8 native local desktop shell
+
+Issue: [#166](https://github.com/ArdurAI/sith/issues/166)
+
+Branch: `gnanirahulnutakki/feat/f11-native-desktop-shell`
+
+Base: `origin/dev` at `c6fa47bb63a269025bfcb3ab9f8042bb02d71edb`
+
+## [G] Goal
+
+Add the first native macOS form of Sith's local fleet IDE without creating a
+second Kubernetes client, a TCP listener, account state, telemetry, or a path
+leak across the UI bridge.
+
+## [D] Decision
+
+- ADR 0010 adopts stable Wails v2 as a thin native shell; Wails v3 remains
+ alpha and is not selected.
+- The native WebView serves the existing `webui.Application` at the exact
+ `wails://wails` origin through Wails' in-process asset-server middleware.
+- The only native bridge method opens a directory chooser. It returns success,
+ cancellation, or a sanitized failure category only; the chosen path and
+ kubeconfig contents never enter JavaScript, diagnostics, or persistent state.
+- A choice creates a bounded kubeconfig-import source and complete replacement
+ in-memory session before atomically replacing the active handler. Failure
+ retains the active session.
+- A replacement switches routing immediately. Requests already leased to the
+ prior session drain before it closes, so one slow request cannot block the
+ new fleet view.
+- `make desktop-build` creates an Apple Silicon development bundle with stable
+ `com.ardurai.sith` identity and an ad-hoc signature. Developer ID signing,
+ notarization, stapling, and release provenance remain E9 follow-up work.
+
+## [A] Red-team review
+
+- The source passes explicit `wails://wails` only to the existing hardened
+ Host/Origin/CSRF/CSP handler; all other non-loopback origins remain rejected.
+- `InProcessHandler` leases the selected session briefly under a mutex, then
+ releases the routing lock before invoking it. Replacement routes new requests
+ immediately and closes the prior application only after its leased requests drain.
+- `sith desktop --kubeconfig-dir` constructs the bounded directory source
+ before the desktop host, avoiding default-kubeconfig hydration before the
+ explicit import validates.
+- Browser mode has no `window.go` bridge, so the import control remains hidden.
+- CodeRabbit's initial staged review found a major close/import race and a
+ minor error-wrapping suggestion. The major race is fixed with terminal host
+ state and a deterministic regression test. The minor is intentionally not
+ applied: native dialog and kubeconfig errors can contain local paths, so the
+ bridge and CLI return stable redacted categories.
+- The explicit hosted CodeRabbit review on PR #167 then found valid packaging,
+ dependency-override, non-starving session-handoff, hydration-status, native
+ signal-shutdown, and documentation gaps. All are fixed in the review
+ checkpoint with focused regression tests. The tool's suggested `-nomodsync`
+ spelling was verified against Wails v2.12.0 and corrected to its actual
+ `-nosyncgomod` flag.
+
+## [T] Tests and evidence
+
+- Focused `go test -race -count=1 ./internal/cli ./internal/webui`: PASS.
+- Replacement-preserves-session and in-flight-handler-replacement tests: PASS;
+ the pair is stable across 50 local repetitions.
+- Final `make ci`: PASS (format, vet, lint, reachable-vulnerability scan with
+ no findings, race tests, safety scripts, performance, binary e2e in 18.265s,
+ and production build).
+- Final `make e2e-isolation`: PASS (forced PostgreSQL RLS tests and 50,000-case
+ cross-workspace selector fuzz campaign).
+- Final `make release-check`: PASS (two verified Darwin/Linux amd64/arm64
+ snapshots, SPDX SBOMs, formula rendering, and deterministic digests).
+- Final `make e2e-kind`: PASS in 158.742 seconds for real two-cluster fleet
+ fanout and OCI image contracts. `kind get clusters` and the Sith-named Docker
+ container check were empty afterward.
+- Final `make desktop-build WAILS=/Volumes/EXTENDED/MacData/go/bin/wails`:
+ PASS with Wails CLI v2.12.0. The resulting app is ARM64, bundle identifier
+ `com.ardurai.sith`, `Signature=adhoc`, and `TeamIdentifier=not set`.
+- `go run ./cmd/sith desktop --help`: PASS with the expected desktop and
+ `--kubeconfig-dir` contract.
+- `git diff --check`: PASS before review/staging.
+
+## [T] Review checkpoint evidence
+
+- PR #167 initial hosted CI: PASS (`build · vet · gofmt · lint · test · e2e`
+ in 10m46s; reproducible archives/SBOM/formula in 5m9s; all CodeQL analyses
+ and the explicit CodeRabbit review completed).
+- Review-fix final `make ci`: PASS (binary e2e 24.797s and production build).
+- Review-fix `make e2e-isolation`, `make release-check`, and `make e2e-kind`:
+ PASS; the final real kind suite took 154.406s and cleaned every temporary
+ cluster.
+- Review-fix desktop bundle: Wails v2.12.0, `-m -nosyncgomod`, verified ARM64,
+ `com.ardurai.sith`, and ad-hoc signature: PASS. The Wails build left
+ `go.mod` unchanged.
+- The local CodeRabbit pass found an unbounded wait in the close/import test;
+ it is corrected with one-second bounds and idempotent source-release cleanup,
+ then verified by focused race tests and the final full CI run.
+- Hosted Linux CI then caught the cancellation-helper test compiling against a
+ macOS-only definition. The helper is now shared while Wails startup remains
+ Darwin-only; focused race suites and the final `make ci` pass after that
+ correction.
+
+## [C] Checkpoint
+
+- Initial signed/DCO/GSTACK implementation checkpoint: `78af530`.
+- Review-fix implementation checkpoint: `b99820e`.
+- Linux-CI portability correction, fresh peer pass, signed/DCO checkpoint,
+ hosted CI, merge, and exact post-merge CI remain to be recorded.