Discover local t3 serve instances for explicit pairing

[colonelpanic8]

Stacked on #4444. Base is main, so until #4444 merges this PR's diff also shows the client-only commit. The reviewable changes are the commits after #4444: local discovery, the credential-free filesystem challenge, and the atomic publication/rollback fix.

What Changed

Let a Linux desktop client find a loopback t3 serve running as the same user and pair with it, without copying a URL out of the terminal.

• A headless server bound to loopback publishes an owner-only presence record (0700 directory, 0600 file) under XDG_RUNTIME_DIR, written atomically via temp+rename, published once, and removed on shutdown. It contains no credential.
• The desktop scans that directory and validates ownership, permissions, size, path containment, startedAt sanity, canonical loopback URLs, and environment identity before presenting a candidate.
• Pairing requires an explicit Pair action. The handshake runs entirely in the Electron main process behind a pairLocalServer(instanceId) IPC, so the renderer receives presence records only — and a credential exactly once, after the click, for the server that was clicked.
• Pairing saves to the encrypted connection catalog and never takes ownership of the server process.

Pairing design — no credential at rest

The advertisement carries no credential. It is presence metadata only: instanceId, pid, startedAt, httpBaseUrl, environmentId, label.

A client proves it is the same local user at pair time, because $XDG_RUNTIME_DIR being 0700 already answers that question:

1. The desktop writes a 256-bit nonce to a 0600 file in $XDG_RUNTIME_DIR/t3code/challenges/.
2. It POSTs { instanceId, challengePath, nonce } to the unauthenticated /api/auth/local-pair.
3. The server requires: discovery active in this process, request arrived over loopback, matching instanceId, realPath on both the directory and the supplied path with containment enforced, a regular 0600 file owned by its own uid and under the size cap, and contents equal to the nonce compared in constant time.
4. Only then is a credential issued — in the HTTP response, never written to disk.
5. The desktop deletes the challenge file in an ensuring block, success or failure.

A different-uid attacker cannot create a file in a directory they do not own, and cannot name an existing one because they would have to supply contents they cannot read. Every check fails closed, and all rejections collapse to a single invalid_credential so the response cannot be used to probe which one tripped. Rejection reasons are logged at debug level only.

The challenge directory is deliberately separate from the advertisement directory, so the server never reads a caller-named path out of the directory it publishes into. The endpoint is closed entirely unless discovery is active, which means non-Linux, non-headless, and non-loopback servers do not expose it at all.

Why this shape. An earlier revision stored a live pairing URL in the advertisement and rotated it every ~4 minutes. Same-UID file access is already sufficient for code execution, so that was defensible — but the credential was AuthAdministrativeScopes, and admin adds AuthAccessWriteScope (mint durable credentials with caller-chosen scopes, revoke other sessions) and AuthRelayWriteScope (relay-link the environment). That turned a passive one-shot file read into persistent, off-machine access, which is exactly the containment the loopback-only argument was supposed to provide.

Removing the credential from disk also deleted the rotation loop, the shutdown revoke, and the tracked-credential state — so a class of liveness bugs went with it.

Known lower-severity items, not addressed here

• TOCTOU between stat/realPath and readFileString, on both the advertisement read and the challenge read. Crosses no privilege boundary: winning it needs write access inside a 0700 directory, i.e. the same UID. Now largely uninteresting on the advertisement side, since winning that race yields a hostname and a label rather than a credential. open+fstat+readAlloc is the correct fix and is expressible in this Effect version, though realPath containment would still be needed since OpenFlag has no O_NOFOLLOW.
• Unbounded scan. No cap on directory entries, and each Pair click re-scans. Same-UID only, but a slice cap would be cheap insurance.
• No stale-file reaping after kill -9. Bounded in practice by tmpfs clearing at logout, and expired records are filtered before the network probe, so they cost only a stat + read.
• The environment-identity probe is a staleness/port-reuse check, not an authenticity check — a hostile local server writes both the record and the probe response. It now carries more weight than before: advertisements no longer expire, so a record left behind by a kill -9'd process is rejected by the probe failing rather than by a timestamp.
• Wrong-uid rejection is not covered by tests. Simulating it needs a file owned by another uid, which requires root or a second account; the suite runs unprivileged. The equal-uid branch is exercised by the happy path.
• Needs manual re-verification against a real t3 serve before merge. This revision reworked a flow that was previously hand-tested end to end in Electron — in particular the challenge file cleanup on failure paths, and that the endpoint is genuinely unreachable on a non-loopback bind.

Checklist

• Post-rebase review-fix verification: formatting and lint across all 55 changed TS/TSX files; 5 affected-package typechecks; 18 focused test files, 130 tests; server route-layer smoke test

• corepack pnpm exec vp check (0 errors; 11 pre-existing unrelated warnings)

• corepack pnpm exec vp run --filter @t3tools/contracts --filter @t3tools/shared --filter t3 --filter @t3tools/desktop --filter @t3tools/web typecheck — clean

• CI=true vitest run apps/desktop/src apps/web/src/components/settings apps/web/src/environments apps/server/src/startupAccess.test.ts apps/server/src/localServerAdvertisement.test.ts packages/shared/src/localServerDiscovery.test.ts — 66 files, 449 tests

• Loopback URL validation exercised against 0x7f.1, 127.1, 2130706433, [::ffff:127.0.0.1], credentials-in-authority, and trailing-dot forms

• Regression test locks in that a discovered pairing URL with a query string is rejected (readHostedPairingRequest honours a host= param)

Note

Add local t3 serve instance discovery and explicit pairing in desktop settings

• Headless t3 serve instances on loopback now publish a signed advertisement file under XDG_RUNTIME_DIR with strict ownership/permission checks; the desktop reads these via a new DesktopLocalServerDiscovery service and exposes them in Connection Settings as 'Available on this computer'.
• A new POST /api/auth/local-pair endpoint validates a filesystem-based nonce challenge and issues a pairing credential; the desktop writes the challenge file, posts it, and calls connectPairing to complete onboarding.
• Introduces a DesktopBackendMode setting (managed | client-only) persisted in app settings and overridable via --backend-mode CLI flag; switching modes schedules an app relaunch and reverts the setting if relaunch fails.
• In client-only mode the desktop skips starting the local backend, serves renderer assets statically or proxies a dev server via a refactored ElectronProtocol discriminated-union registration (source: 'proxy' | 'static'), and suppresses local environment bootstraps and primary environment target resolution.
• UI components (Sidebar, CommandPalette, thread status indicators, project grouping) now use a new EnvironmentPresenceScope to classify environments as remote when the app owns no local backend.
• Risk: local server advertisement and pairing are Linux-only (requires XDG_RUNTIME_DIR); macOS/Windows instances will not be discovered.

^{Macroscope summarized 4624c4b.}

---

Note

High Risk
Touches authentication bootstrap (/api/auth/local-pair), credential issuance, and desktop startup/shutdown paths; pairing security depends on filesystem and loopback checks being correct on Linux.

Overview
This PR lets the desktop run without spawning a managed backend (client-only mode), discover loopback t3 serve processes on Linux, and pair on an explicit user action—credentials are issued only in the HTTP response, not stored in advertisement files.

Desktop backend mode — Persisted backendMode plus --backend-mode CLI override is latched at startup. In client-only, bootstrap skips the backend pool, registers IPC, and opens the window on renderer readiness (dev proxy or packaged static assets via new source: "static" protocol handling with SPA fallback and path checks). Shutdown no longer stops backends in this mode. Settings changes that require a different effective mode trigger relaunch (with rollback if relaunch fails).

Local discovery & pairing — Headless loopback Linux servers publish a credential-free JSON advertisement under XDG_RUNTIME_DIR while LocalServerDiscoveryState is active. The desktop scans, validates permissions/loopback/identity via probe, and exposes discoverLocalServers / pairLocalServer IPC (handshake in main process: write 0600 nonce challenge, POST to /api/auth/local-pair, validate pairing URL, always delete challenge). Server adds localPair auth handler with fail-closed filesystem proof (loopback, instance match, contained challenge path, owner/mode/size, constant-time nonce compare) before issuing a startup pairing credential.

UI & presence — Connections settings logic for pairing candidates; sidebar/command palette use environment presence scope so remote vs local labeling respects whether the app owns a local environment.

^{Reviewed by Cursor Bugbot for commit 4624c4b. Bugbot is set up for automated code reviews on this repo. Configure here.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: a785a55a-8f3e-43b9-90ba-ac92f97bab88

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[macroscopeapp]

Approvability

Verdict: Needs human review

This PR introduces a significant new feature: local server discovery and pairing with a new authentication mechanism. It adds a credential-issuing endpoint (/api/auth/local-pair) using filesystem-based challenge/response authentication, new desktop backend modes, and substantial UI changes. The authentication and security implications warrant careful human review.

^{You can customize Macroscope's approvability policy. Learn more.}

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 2 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 00de753. Configure here.}