CLAUDE.md@desktop · diff
git:20260829.e99a1c7 to git:20260830.65d3802
33 added, 7 removed. Audit A to A.
What this update changes in the checks
No check changed: every fixed check gives the same answer before and after this update.
A tripped check is a label, not a verdict: read the matched text and the lines below. This week's updates that newly trip a check.
# Duct Desktop — Claude Code instructions
Thin Tauri v2 shell around the hosted Duct web app, plus an OS-keychain store
for bring-your-own provider API keys. Design:
`docs/engineering/tauri-desktop-byo-keys-plan.md`.
## Stack
- **Tauri v2** (Rust core) + the system webview. No bundled frontend in the
alpha — the window loads the hosted URL (`app.getduct.ai`, set in
`src-tauri/tauri.conf.json`). GA may switch to a bundled static export.
- **Keychain** via the `keyring` crate; commands in `src-tauri/src/lib.rs`
(`get_provider_key` / `set_provider_key` / `delete_provider_key`). The web app
calls them through `window.__TAURI__.core.invoke` (`app/src/lib/providerKeys.js`).
- - **Browser-based Google sign-in**: the web app probes `get_shell_info` (version +
- `capabilities.browserAuth`) and calls `open_external` (http/https only) to run
- OAuth in the system browser; the backend redirects back via the
- `ai.getduct.desktop://auth?auth_code=...` deep link (tauri-plugin-deep-link),
- which the shell forwards to the webview as `/?auth_code=`. New shell-dependent
- web flows must be gated on a `get_shell_info` capability flag, never on version
- sniffing — old shells keep the legacy path.
+ - **Browser-based OAuth**: *every* OAuth flow runs in the system browser, because
+ Google refuses it inside an embedded webview and a user in one has none of
+ their browser's sessions, passwords or passkeys. The web app probes
+ `get_shell_info` and calls `open_external` (http/https only) to launch the
+ authorize URL; the backend redirects back via a
+ `ai.getduct.desktop://` deep link (tauri-plugin-deep-link) that the shell
+ forwards into the webview. Two routes, same shape:
+ - `//auth?auth_code=` → `/?auth_code=` — signing in to Duct
+ (`capabilities.browserAuth`, `backend/routes/signin.py`).
+ - `//connector?connector=&auth_code=` → `/connections?connector=&auth_code=`
+ — connecting a data source (`capabilities.browserConnectors`,
+ `backend/routes/auth.py`, started by `app/src/lib/connectorAuth.js`).
+
+ **No credential ever rides in a deep link.** Any app on the machine can claim
+ the scheme, so both routes carry only a single-use 60-second code that the
+ webview redeems against the backend (`/auth/exchange`,
+ `/auth/connectors/exchange`). This matters more for connectors than for
+ sign-in: their payload is a *long-lived* Google refresh token, where the
+ in-browser flow can still use a URL fragment (never sent to a server) because
+ it never leaves the app's own window.
+
+ Both flows also route their failures to the app's `/desktop-auth` relay page
+ rather than raising. The system browser renders whatever the loopback sidecar
+ returns, so an `HTTPException` there is a bare `{"detail": ...}` on a white
+ page — a dead end reached *after* the user already approved at Google.
+
+ New shell-dependent web flows must be gated on a `get_shell_info` capability
+ flag, never on version sniffing — old shells keep the legacy path.
+ - **`target="_blank"` links are dead in the webview** (no tabs, no window
+ opening) and are rerouted to the system browser by
+ `installExternalLinkHandler` in `app/src/lib/shell.js`, mounted once by
+ `LocalBackendGate`. It deliberately only touches anchors that already asked
+ for a new tab; a link meant to navigate this window still does.
- macOS registers the custom scheme from the built bundle's Info.plist, so the
deep-link leg only works from a bundled app (`tauri build`), not `tauri dev`.
- **Local backend ("sidecar")**: the bundle ships the FastAPI backend frozen by
PyInstaller (`backend/duct_sidecar.spec`), supervised by
`src-tauri/src/sidecar.rs`. It binds a loopback port the OS picks, persists to
SQLite in the per-user data dir, and prints one JSON handshake line the shell
reads. The web app gets it via `get_sidecar_info` and repoints its API base
(`app/src/lib/localBackend.js`), gated on the `localSidecar` capability.
Build it before bundling — `cd backend && poetry run pyinstaller
duct_sidecar.spec --noconfirm` — because `bundle.resources` copies
`backend/dist/duct-sidecar/` verbatim and a stale or missing build ships a
broken app. It is **onedir, never onefile**: a onefile binary unpacks to a
temp dir at startup and does not survive signing + notarization.
- **Windows and Linux** ship from the same pipeline: NSIS on Windows, deb +
AppImage on Linux, each with its own PyInstaller sidecar (a frozen CPython
tree is per-OS, never cross-compiled). Two platform differences are load
bearing and easy to regress:
`tauri-plugin-single-instance` (registered **first**, before every other
plugin) — macOS hands a deep link to the running app, but Windows and Linux
start a *second* process with the URL in argv, which for this app means a
second window and a second sidecar with the auth code in the wrong one; and
`CREATE_NO_WINDOW` in `sidecar.rs`, without which every Windows launch pops a
console window (the sidecar must stay a console binary — its stdout is the
handshake). Windows builds are **not** Authenticode-signed yet, so SmartScreen
warns on first run.
- **Self-update** is wired: `tauri-plugin-updater` behind a default-on `updater`
cargo feature, driven from the web app through `check_for_update` /
`install_update` (not the plugin's JS bindings — the window loads a remote
origin and cannot import them, which is also why no `updater:*` permission is
needed: those gate the plugin's JS API, and our commands reach it from Rust).
The manifest is `latest.json` on the GitHub release, assembled by
`.github/scripts/build-updater-manifest.mjs`. The App Store build drops it with
`--no-default-features`, which removes the plugin and flips `get_shell_info`'s
`autoUpdate` to false; the two commands stay compiled as inert stubs so the
capability files are identical across builds. **The minisign private key is not
recoverable** — losing it means no installed copy will ever accept another
update.
- **macOS distribution** is Developer ID + a notarized DMG, *not* the App Store.
The sandbox cannot host a PyInstaller sidecar and embedded interpreters draw
rejections — see the engine consolidation review (duct-cloud, private) §8.2.
Config is `src-tauri/tauri.conf.json` (`bundle.macOS`) +
`src-tauri/Entitlements.developerid.plist`. The App Store variant
(`tauri.appstore.conf.json`, `Entitlements.appstore.plist`,
`.github/workflows/desktop-testflight.yml`) is retained only for the thin
client that predates the sidecar; do not add the sidecar to it. That workflow
is **manual-only** — `bundle.resources` now always declares the sidecar, which
an App Store build cannot host, so it fails on every desktop change until the
appstore overlay overrides `bundle.resources`.
## Crash reporting
Three processes, one consent decision (`src/telemetry.rs`):
- **The shell** initialises `sentry` in-process. Before this, a Rust panic or a
sidecar that would not start left no trace anywhere — the webview's Sentry
only ever sees JavaScript.
- **The sidecar** stays silent by default. `local_server.py` blanks
`SENTRY_DSN` on purpose ("a user's laptop is not a deployment"), and
`sidecar.rs` passes a real DSN through *only* when the user has opted in. It
also has to pass `SENTRY_ENABLE_LOCALHOST=1`, because the sidecar binds
127.0.0.1 and `server.py` otherwise treats that as "not deployed" and drops
every event.
- **The webview** already reported, but was indistinguishable from a browser
session; `instrumentation-client.ts` now tags `shell`, `shell.version` and
`shell.localSidecar`.
Consent is opt-IN, stored as `telemetry.json` in the per-user data dir — a
preference, not a secret, so not the keychain. A missing, unreadable, or
malformed file all mean *off*: consent is never inferred from a failed read.
The DSN is compiled in via `SENTRY_DSN` — the same name the backend reads and
`backend/.env.local` already defines, so there is one spelling across all three
processes. With no DSN the whole path is inert and the settings card hides
itself rather than offering a switch that changes nothing.
The data-dir path is duplicated between `telemetry.rs` and `utils/appdirs.py`
by necessity — the shell must resolve it *before* the sidecar exists to ask.
Change one, change the other.
## Rules
- Keep this shell thin: no agent code, prompts, or secrets ever ship here.
- Provider keys live only in the OS keychain — never write them to disk or logs.
- Any origin the webview loads must be listed under `remote.urls` in
`src-tauri/capabilities/default.json` for `invoke` to work.
- **A new `#[tauri::command]` needs three edits, not one.** Add it to
`generate_handler!` in `src/lib.rs`, to `AppManifest::commands` in `build.rs`,
and as `allow-<kebab-command>` in every capability that needs it. App commands
are allowed by default only for *local* content — this window loads a remote
origin, and a capability can only grant permissions that exist, so skipping
`build.rs` makes the command unreachable with
`<command> not allowed. Plugin not found`. The JS side swallows that
(`getShellInfo()` returns null, `providerKeys.js` degrades), so it fails
silently rather than loudly.
- Local dev origins live in `capabilities/dev-localhost.json`, kept out of
release builds by `app.security.capabilities` in `tauri.conf.json` (unset
means *all* capability files ship). Only `tauri.dev.conf.json` opts it in.
- `app.security.capabilities` selects which files are *loaded*, but `tauri-build`
**validates every file in `capabilities/`** regardless. So a capability naming
a permission from a conditionally-compiled plugin fails the build for
configurations that never load that file — which is what a separate `updater`
capability did to the `--no-default-features` App Store build. Keep permissions
from optional plugins out of `capabilities/` entirely.
- Building needs platform webview libraries (see `README.md`); it does not build
in the Claude-on-the-web container — build, sign, and release locally or in CI.
- `Cargo.lock` is committed; refresh it with `cargo generate-lockfile` (or a
build) when dependencies change, and commit the result.
- The desktop sidecar runs **Alembic**, not `create_all` (`backend/db/migrate.py`).
Every new migration must therefore be SQLite-safe — JSON columns via
`sa.JSON().with_variant(JSONB, 'postgresql')`, `alter_column` inside
`op.batch_alter_table`. The pre-baseline revisions are Postgres-only and are
never replayed; `backend/tests/test_desktop_migrations.py` guards the path
that is.
- Changes to `src-tauri/Entitlements.appstore.plist` alter what the sandbox
allows. Adding an entitlement without a real need invites App Review questions;
removing `app-sandbox` breaks the upload outright (CI checks for it).
- `src-tauri/Entitlements.developerid.plist` is the opposite case: every key in
it is load-bearing for the embedded CPython interpreter under the hardened
runtime. Removing one does not harden the app, it makes the sidecar crash at
launch. It deliberately carries no `app-sandbox` key.
- The whole `bundle` config uses `deny_unknown_fields`, not just `bundle.macOS`
— a mistyped key fails the build rather than being ignored, and JSON has no
comments, so there is nowhere to explain a setting *in* the config. An
explanatory `"comment"` key fails with `Additional properties are not allowed`.
Explain overlay settings here or in `README.md` instead. Key names are
camelCase (`minimumSystemVersion`, `hardenedRuntime`, `entitlements`).
- `bundle.createUpdaterArtifacts` applies to the macOS `app` target too, so
`--bundles app` does not opt out of it. Both overlays that must not produce a
signed archive turn it off explicitly: `tauri.dev.conf.json` (a dev build has
no signing key, and would otherwise fail *after* writing the `.app`) and
`tauri.appstore.conf.json`. On this app that archive is a ~160 MB gzip of the
470 MB bundle — about 85 seconds per build.
## Versioning
The shell is the monorepo's only versioned installable — `app/` and `backend/`
deploy continuously and have no version ritual. The shell version is
`MAJOR.MINOR.PATCH`, digits and dots only (Apple rejects suffixes like
`-beta`), and lives in **two files that must always match**:
`src-tauri/tauri.conf.json` `version` and `src-tauri/Cargo.toml` `version`.
Refresh `Cargo.lock` after changing Cargo.toml; `get_shell_info` reports the
Cargo value to the web app.
SemVer here is measured against the **shell↔web contract**: the invoke
commands, the `get_shell_info` capability flags, the `ai.getduct.desktop://`
deep-link scheme, the keychain service/format, and the origins allowed to
invoke. Bump in the same PR as the change, at most one bump per PR:
- **MAJOR** — a capable web app or existing user data breaks against the new
shell: removing or renaming an invoke command or capability flag, changing
the deep-link scheme or keychain service name, raising
`minimumSystemVersion`. `1.0.0` itself is reserved for the first public
(non-TestFlight) release.
- **MINOR** — new capability, backwards compatible: a new invoke command, a
new capability flag, a new deep-link route, a new entitlement.
- **PATCH** — behaviour fixes with no contract change: bug fixes, security
fixes, UI/icon polish, dependency bumps.
- **No bump** — nothing that ships in the bundle changed: CI workflow edits,
docs, comments. Markdown-only changes under `desktop/` are excluded from the
TestFlight workflow's path filter for the same reason. Rebuilds of the same
version are already distinguished by the CI-stamped build number.
While the version is `0.y.z` (pre-GA), contract-breaking changes bump MINOR
instead of MAJOR — but must still be called out in the PR description.
Never set the build number by hand — CI stamps the GitHub run number as
`CFBundleVersion`, which App Store Connect requires to keep increasing — and
never gate web-app behaviour on the version string; probe
`get_shell_info().capabilities` instead.