Shadowbroker/desktop-shell/tauri-skeleton

Tauri Skeleton

Cross-platform Tauri integration for the ShadowBroker desktop boundary.

Scope

This skeleton covers the accepted native desktop foundation:

• Rust-authoritative local-control policy enforcement and audit
• cross-platform tray/menu-bar lifecycle
• packaged managed local backend runtime
• packaged loopback runtime for same-origin /api/*
• optional reduced-trust browser companion opener
• desktop packaging flow with branded bundle icons and release manifests

It does not move DM/data-plane operations into native code.

Architecture

1. main.rs creates the main window programmatically and attaches an initialization_script so window.__SHADOWBROKER_DESKTOP__ exists before page JavaScript runs
2. bridge.rs routes Tauri IPC through policy.rs before any privileged backend dispatch
3. backend_runtime.rs installs and launches the bundled backend runtime into app-local writable storage for packaged builds
4. companion_server.rs provides the packaged loopback HTTP origin used by:
   • the native main window for ordinary same-origin /api/*
   • the optional external browser companion opener
5. tray.rs owns tray/menu-bar restore/hide/quit behavior
6. http_client.rs forwards privileged native requests with the native-owned admin key

Environment variables

• SHADOWBROKER_BACKEND_URL - Optional backend override. In packaged mode, if unset, the app launches its bundled local backend automatically.
• SHADOWBROKER_ADMIN_KEY - Optional admin key for privileged backend access
• SHADOWBROKER_FRONTEND_URL - Explicit frontend origin override for dev/custom setups

Development

# Install Tauri CLI
cargo install tauri-cli@^2

# Start the dev shell (frontend dev server must already be running on :3000)
./dev.sh

Platform dependencies:

• Linux: libwebkit2gtk-4.1-dev, libjavascriptcoregtk-4.1-dev, libayatana-appindicator3-dev, libxdo-dev
• macOS: Xcode command-line tools
• Windows: Visual Studio C++ build tools

Production build

Use whichever entrypoint matches your environment:

# POSIX shell
./build.sh

# Windows PowerShell
./build.ps1

# Cross-platform npm wrapper from repo root
npm --prefix desktop-shell run build:desktop

Add --clean when you want a fresh export/icon rebuild and old bundle artifacts removed before packaging.

The release build now does the full packaging pipeline:

1. Generates branded icons in src-tauri/icons/
2. Stages a desktop-only frontend export tree that omits Next server-only routes/middleware (src/app/api, src/middleware.ts)
3. Stages a managed backend runtime bundle from backend/ into src-tauri/backend-runtime/
4. Builds the frontend export with NEXT_OUTPUT=export
5. Copies frontend/out to src-tauri/companion-www/
6. Runs cargo tauri build
7. Writes SHA256SUMS.txt and release-manifest.json to src-tauri/target/release/bundle/

If cargo tauri is not installed, the build now fails immediately with the required install command instead of failing after the frontend export.

See RELEASE.md for the release-oriented checklist. See RELEASE_INPUTS.md for the future credentials/secrets that only matter once you want signed/notarized public distribution.

Runtime model

Native privileged path

The 27 privileged local-control commands still go through the Rust IPC bridge. The packaged loopback server does not replace that boundary.

Packaged loopback app server

In packaged builds, main.rs now launches a bundled local backend by default, then starts a loopback HTTP server and points the native window at it. That gives the packaged desktop app ownership of both the app shell and the local backend runtime, while keeping a real same-origin /api/* path for ordinary non-privileged fetches.

The managed backend runtime also seeds and persists its own local secrets on first launch:

• ADMIN_KEY
• MESH_PEER_PUSH_SECRET
• MESH_DM_TOKEN_PEPPER
• MESH_SECURE_STORAGE_SECRET on non-Windows

It also defaults the managed compatibility-cutoff flags to the hardened desktop posture:

• MESH_BLOCK_LEGACY_NODE_ID_COMPAT=true
• MESH_ALLOW_LEGACY_NODE_ID_COMPAT_UNTIL= unless an operator sets a dated temporary migration override
• MESH_BLOCK_LEGACY_AGENT_ID_LOOKUP=true

That keeps the packaged desktop path out of the "edit .env by hand before it is safe" trap for normal local users.

If a managed desktop operator leaves MESH_BLOCK_LEGACY_NODE_ID_COMPAT=false in the managed backend .env, bootstrap now normalizes it back to true. The only supported escape hatch for legacy 16-hex node IDs is a dated MESH_ALLOW_LEGACY_NODE_ID_COMPAT_UNTIL=YYYY-MM-DD override. Source/server deployments remain operator-controlled through their own env files and do not inherit this desktop-specific default.

Browser companion

Browser companion is:

• optional
• disabled by default
• loopback-only
• reduced-trust

It does not receive the native bridge injection and is not equivalent to standalone browser mode. The built-in loopback server is a thin static /api/* proxy and does not reproduce Next middleware, admin-session cookie logic, or wormhole routing.

Current status

This is now a runnable desktop build path with branded assets and repeatable bundle outputs.

What works:

• Native desktop window (dev + packaged)
• Packaged bundled local backend launch + ownership
• Managed packaged backend auto-seeding of local admin/private-plane secrets
• Packaged same-origin /api/* path for non-privileged data
• Rust-authoritative policy enforcement and audit
• Tray/menu-bar background lifecycle
• macOS dock reopen restores the main window
• Browser companion opener with honest reduced-trust scoping
• Branded bundle icon set (.png, .ico, .icns, Windows tile assets)
• Release checksums + artifact manifest alongside bundle output
• GitHub Actions desktop build matrix for Windows/macOS/Linux
• Tag-driven GitHub release asset upload without required secrets

What is still not done:

• Windows code signing
• macOS notarization credentials
• Auto-update publishing
• Final installer copy / splash polish
• Standalone-browser-equivalent companion parity