desktop-client init

Author: K. Kaushik Reddy

.github/workflows/desktop-release.yml

@@ -0,0 +1,93 @@
+name: desktop-release
+
+# Builds the DeepSQL desktop client for every platform. Each OS builds its own
+# targets on its own runner: cross-building Windows needs Wine and Linux targets
+# need a matching glibc, and both are far less reliable than just using the
+# native runner.
+#
+# Tag-triggered runs attach the installers to the GitHub release. Manual runs
+# upload them as workflow artifacts, which is the easy way to hand a build to a
+# colleague before there is a release to cut.
+
+on:
+  push:
+    tags:
+      - 'desktop-v*'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: ${{ matrix.name }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - { os: macos-latest, name: macOS, target: '--mac' }
+          - { os: windows-latest, name: Windows, target: '--win' }
+          - { os: ubuntu-latest, name: Linux, target: '--linux' }
+
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions/setup-node@v7
+        with:
+          node-version: 22
+          cache: npm
+          cache-dependency-path: desktop/package-lock.json
+
+      - name: Install dependencies
+        working-directory: desktop
+        run: npm ci
+
+      - name: Self-test the SSH tunnel transport
+        # Runs a real SSH server in-process, so it needs a display-free Electron.
+        # xvfb is only required on Linux; the other runners have a window server.
+        working-directory: desktop
+        run: ${{ matrix.os == 'ubuntu-latest' && 'xvfb-run --auto-servernum npm run selftest:tunnel' || 'npm run selftest:tunnel' }}
+        shell: bash
+
+      - name: Build installers
+        working-directory: desktop
+        env:
+          # Signing is skipped when these are unset; electron-builder warns and
+          # produces unsigned artifacts rather than failing the build.
+          CSC_LINK: ${{ secrets.DESKTOP_CSC_LINK }}
+          CSC_KEY_PASSWORD: ${{ secrets.DESKTOP_CSC_KEY_PASSWORD }}
+          APPLE_ID: ${{ secrets.APPLE_ID }}
+          APPLE_APP_SPECIFIC_PASSWORD: ${{ secrets.APPLE_APP_SPECIFIC_PASSWORD }}
+          APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
+        run: npx electron-builder ${{ matrix.target }} --publish never
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: deepsql-desktop-${{ matrix.name }}
+          if-no-files-found: error
+          path: |
+            desktop/release/*.dmg
+            desktop/release/*.zip
+            desktop/release/*.exe
+            desktop/release/*.AppImage
+            desktop/release/*.deb
+            desktop/release/*.rpm
+
+  release:
+    name: attach to release
+    needs: build
+    if: startsWith(github.ref, 'refs/tags/desktop-v')
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          path: artifacts
+          merge-multiple: true
+
+      - uses: softprops/action-gh-release@v2
+        with:
+          files: artifacts/*
+          fail_on_unmatched_files: true

AGENTS.md

@@ -110,6 +110,27 @@ User Message → ChatController → SpringAIChatService
 - **UI state**: Zustand stores with selector hooks (`useActiveTab`, `useDashboardActions`)
 - **Independent chat threads**: Per-tab, per-connection, stored in localStorage
 
+## Desktop Client (Electron)
+
+`desktop/` is a standalone Electron app (its own `package.json`, not part of the
+root npm project). It is a **thin client**: it never bundles the React frontend,
+it navigates a `WebContentsView` at the real DeepSQL origin, so the UI is always
+the version the server runs. Two transports resolve to that origin — direct TLS,
+or an in-process SSH local forward (`ssh2`, no `ssh` binary needed).
+
+| Path | Purpose |
+|------|---------|
+| `desktop/src/main/transport.js` | Transport manager: connect/disconnect/health per profile |
+| `desktop/src/main/tunnel.js` | SSH local forward, host-key TOFU-then-strict, auto-reconnect |
+| `desktop/src/main/tls.js` | Cert policy (system / pinned / custom CA / TOFU) for Node **and** Chromium |
+| `desktop/src/main/profiles.js` | Connection profiles; secrets only as `safeStorage` ciphertext |
+| `desktop/src/main/windows/workspace.js` | Frameless shell: native chrome + embedded DeepSQL view |
+| `desktop/src/renderer/shared/theme.css` | Mirrors `src/index.css` tokens — keep in step |
+
+No backend change was needed: `docker/nginx/default.conf` already serves the SPA,
+`/api` and `/agent-api` from one origin, which is what makes the thin-client
+model work without CORS or cookie special-casing.
+
 ## Performance & Safety Guardrails
 
 - Log size cap (500MB) via stream wrappers

CLAUDE.md

@@ -122,6 +122,72 @@ mcp/                # DeepSQL Phase 1 MCP server (Node stdio wrapper around back
 agent/              # DeepSQL Agent (persona, skills, skins, Dockerfile for the Compose service)
 ```
 
+## Desktop Client (`desktop/`)
+
+Cross-platform Electron client for a self-hosted DeepSQL VM. **Separate npm
+project** — `cd desktop && npm install`, not part of the root `package.json`.
+
+```bash
+cd desktop
+npm start                 # run     npm run dev          # run with DevTools
+npm run dist:mac          # dmg + zip (arm64 + x64), also :win / :linux
+npm run smoke -- --url https://deepsql.example.com   # headless connection check
+npm run selftest:tunnel   # end-to-end SSH tunnel test (in-process SSH server)
+```
+
+**It is a thin client and deliberately does not bundle the React frontend.** It
+navigates a `WebContentsView` at the real DeepSQL origin, so the UI is always the
+version the VM is running — no bundle/backend skew, and no second copy of 40+
+tabs to maintain. This works with **zero backend changes** because
+`docker/nginx/default.conf` already serves the SPA, `/api` and `/agent-api` from
+one origin: cookies, CORS and SSE behave exactly as in a browser. Do not
+"improve" this by bundling `dist/` — that reintroduces CORS, `SameSite`, and
+version-skew problems the current design does not have.
+
+**Two transports, one abstraction.** Both resolve to an *origin*, so nothing
+downstream of `desktop/src/main/transport.js` knows which is in use:
+
+- **Direct TLS** — the VM's HTTPS origin. Four certificate modes (`system`,
+  `pinned`, `custom-ca`, `insecure`/TOFU), applied to **both** the Node health
+  probe and the Chromium session (`tls.applyToSession`). Applying it to only one
+  gives a connection that tests green but renders a certificate error.
+- **SSH tunnel** — `ssh2` local forward, loopback-bound, no `ssh` binary needed.
+  The local port is *sticky* across launches on purpose: the origin includes the
+  port, and a fresh random port would silently reset the web app's
+  `localStorage`. `http://127.0.0.1:*` is a Chromium secure context, so the
+  backend's `Secure` cookies still work over the tunnel. **Forward to the
+  frontend container (3000), not a host reverse proxy on :80** — that proxy
+  matches on `server_name`, a tunnel arrives with `Host: 127.0.0.1:<port>`,
+  and the request lands on the default vhost as a 404 that reads like a broken
+  backend. The container's nginx uses `server_name _` and answers any Host.
+
+Three non-obvious things, all found the hard way:
+
+1. **`Client.connect({ privateKey })` must get the raw key material, not the
+   object `sshUtils.parseKey` returns.** Handed a parsed key, ssh2 silently
+   never offers the publickey method and the server replies with a bare
+   authentication failure — a symptom that points at the VM's `authorized_keys`
+   rather than at a type mismatch on our side. `loadPrivateKey` parses only to
+   produce good error messages and returns the buffer.
+2. **Authentication succeeding says nothing about forwarding being allowed.**
+   A hardened sshd (`AllowTcpForwarding no`) accepts the login and refuses every
+   `direct-tcpip` channel; the failure otherwise surfaces as "socket hang up" on
+   the first browser request, pointing nowhere near sshd. `verifyForwarding()`
+   opens and closes one channel right after auth and classifies the refusal by
+   SSH reason code — 1 (`ADMINISTRATIVELY_PROHIBITED`, verified against real
+   OpenSSH) names `AllowTcpForwarding`, 2 (`CONNECT_FAILED`) means nothing is
+   listening on the remote port.
+3. **Only a session that once reached `ready` may be reconnected.** Gating
+   reconnects on `everReady` is what stops a connect that fails on
+   authentication from retrying forever behind a caller that already surfaced
+   the error.
+
+Secrets (key passphrases, SSH passwords) are stored as `safeStorage` ciphertext;
+where no OS keychain exists nothing is written to disk and the launcher says so.
+Each profile gets its own session partition, so two DeepSQL servers never share
+cookies. `.github/workflows/desktop-release.yml` builds all three platforms on
+their native runners. See `desktop/README.md` for the full picture.
+
 ## MCP Server
 
 - `mcp/deepsql-phase1-server.js` implements a Phase 1 stdio MCP server for internal rollout.

desktop/.gitignore

@@ -0,0 +1,4 @@
+node_modules/
+release/
+build/icon.iconset/
+*.log