feat(desktop): Tauri v2 kiosk shell — maximized window, prod right-click block, auto-update + code-signing

Add apps/desktop, a thin Tauri v2 shell wrapping the SAME @parking/web SPA so
the desktop and browser UIs never drift: dev loads the Vite dev server (HMR),
prod bundles the web app's dist/. No business logic in the shell (device/auth/
ledger stay in @parking/server); deny-by-default capabilities.

apps/web (single UI source of truth):
- lib/origin.ts: centralize the backend origin (API_BASE/apiUrl/wsUrl from
  VITE_API_BASE); no-op in the browser, lets the desktop build target Fastify.
- lib/kiosk.ts: block the right-click context menu in PROD only (dev keeps it +
  devtools).
- lib/desktop-updater.ts: prompt-on-update auto-update (no-op in browser/offline)
  → downloadAndInstall + relaunch; i18n update.* keys (sq+en).
- .env.production: VITE_API_BASE wired to the Fastify origin for the bundle.

Desktop:
- window starts maximized (not fullscreen — operator keeps OS access).
- auto-update via tauri-plugin-updater + -process; self-hosted endpoint is a
  PLACEHOLDER to fill in. Updater keypair: pubkey embedded in tauri.conf.json;
  private key + password kept OUTSIDE the repo (~/.parking-updater-keys) and as
  TAURI_SIGNING_* build secrets.
- Turbo build is a no-op; the real signed bundle is `pnpm --filter
  @parking/desktop bundle` (verified → .deb/.rpm/.AppImage + .sig signatures).

Verified: cargo check clean; turbo run build lint 14/14 green; i18n parity holds;
no key/sig/bundle artifacts in the repo.

Wiki (security + desktop analysis recorded alongside):
- new concepts/tpm.md (TPM 2.0: how it works, sealed-LUKS auto-unlock + non-
  extractable signing key, limits — live-root, bus-sniff — TPM-vs-ATECC608 by
  platform).
- new decisions/desktop-shell-tauri.md (Tauri v2 over Electron; best-case Ubuntu
  26.04 LTS, worst-case Windows+WSL → kiosk browser; full as-built).
- pull-the-disk attack trace on append-only-event-chain; ATECC608 not-in-a-PC
  caveat; cross-links from disk-os-hardening / threat-model.
- open-questions #11 (appliance WebKitGTK), #12 (TPM hardening impl), #13
  (startup verifyChain self-check); index/overview/log/standing-decisions.

Claude-Session: https://claude.ai/code/session_01Xcm6ikLgGoCxxHrxtjkk5V

apps/desktop/.env.example

@@ -0,0 +1,10 @@
+# Desktop (Tauri) build — the @parking/web SPA needs to know where Fastify is.
+#
+# In a BROWSER (dev via the Vite proxy, or prod where Fastify serves the SPA),
+# leave VITE_API_BASE UNSET — requests stay relative/same-origin.
+#
+# For the DESKTOP build, the bundled SPA loads from tauri://localhost and has no
+# proxy, so point it at the appliance's Fastify origin. This is read at WEB build
+# time, so export it before `pnpm --filter @parking/desktop build` (or put it in
+# apps/web/.env.production).
+VITE_API_BASE=http://127.0.0.1:3000

apps/desktop/.gitignore

@@ -0,0 +1,3 @@
+# Rust / Tauri build artifacts
+src-tauri/target/
+src-tauri/gen/

apps/desktop/README.md

@@ -0,0 +1,42 @@
+# @parking/desktop — Tauri v2 kiosk shell
+
+A **thin native desktop window** over the `@parking/web` SPA. It contains **no UI and no business
+logic** of its own: the window renders the *same* web app the browser does, so the desktop and the
+browser stay identical and never drift. Device/auth/ledger logic stays in `@parking/server`. See
+`wiki/decisions/desktop-shell-tauri.md`.
+
+## How the "same look & functionality" guarantee works
+
+| | Source of the UI |
+| --- | --- |
+| **Dev** (`tauri dev`) | the window loads `http://localhost:5173` — the **`@parking/web` Vite dev server**. Edit a component in `apps/web` → HMR updates the desktop window live. |
+| **Prod** (`tauri build`) | the window bundles `apps/web`'s built `dist/`. `beforeBuildCommand` rebuilds the SPA first. |
+
+There is only one UI codebase (`apps/web`); this package just wraps it.
+
+## Backend connection
+
+The SPA talks to Fastify over HTTP/WS. In a browser that's same-origin (relative `/api`). In the
+desktop build the bundled assets load from `tauri://localhost`, so set **`VITE_API_BASE`** (read at
+web build time — see `.env.example`) to the appliance's Fastify origin, e.g.
+`http://127.0.0.1:3000`. The CSP `connect-src` in `tauri.conf.json` is already allowed for that
+origin, and the backend must include the Tauri origin in `WS_ALLOWED_ORIGINS` for the live feed.
+
+## Commands
+
+```bash
+pnpm --filter @parking/desktop dev      # native window over the web dev server (HMR)
+pnpm --filter @parking/desktop bundle   # build the SPA + bundle the desktop app (.deb/.rpm/.AppImage)
+```
+
+> `build` is a **no-op** in this package so `turbo run build` stays fast — the real desktop bundle
+> (compiles Rust, minutes long) is the explicit `bundle` script above.
+
+Requires the Rust toolchain and (on Linux) WebKitGTK 4.1 + libsoup-3 dev libraries. Under WSL2 the
+window needs a display (WSLg or an X server).
+
+## Not here (deliberately)
+
+Kiosk lockdown (fullscreen/no-decorations), auto-update, code signing, and launching Fastify from
+the shell are out of scope for the scaffold — on the appliance Fastify runs as its own service and
+this shell connects to it.

apps/desktop/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@parking/desktop",
+  "version": "0.0.0",
+  "private": true,
+  "//": "Tauri v2 desktop shell — a THIN native window over the @parking/web SPA. No business logic lives here (device/auth/ledger stay in @parking/server); see wiki/decisions/desktop-shell-tauri.md. Dev loads the web dev server (HMR); build bundles the web app's dist/, so the desktop UI and the browser UI are the SAME codebase and never drift.",
+  "type": "module",
+  "scripts": {
+    "dev": "tauri dev",
+    "build": "echo 'no-op in the Turbo graph — the real desktop bundle is a deliberate `pnpm --filter @parking/desktop bundle` (compiles Rust + packages installers, minutes long)'",
+    "bundle": "tauri build",
+    "tauri": "tauri",
+    "lint": "echo 'no JS lint (Tauri shell; Rust checked via cargo)'"
+  },
+  "devDependencies": {
+    "@tauri-apps/cli": "^2.9.1"
+  },
+  "dependencies": {
+    "@tauri-apps/plugin-process": "^2.3.1",
+    "@tauri-apps/plugin-updater": "^2.10.1"
+  }
+}

apps/desktop/src-tauri/Cargo.toml

@@ -0,0 +1,28 @@
+[package]
+name = "parking-desktop"
+version = "0.0.0"
+description = "Parking System — desktop kiosk shell"
+edition = "2021"
+rust-version = "1.77"
+
+# Thin Tauri v2 shell. Deliberately holds NO business logic — it loads the
+# @parking/web SPA and lets it talk to the local Fastify server. Device/auth/
+# ledger stay server-side. See wiki/decisions/desktop-shell-tauri.md.
+
+[lib]
+name = "parking_desktop_lib"
+crate-type = ["staticlib", "cdylib", "rlib"]
+
+[build-dependencies]
+tauri-build = { version = "2", features = [] }
+
+[dependencies]
+tauri = { version = "2", features = [] }
+serde_json = "1"
+# Auto-update: prompt the operator, download a signed update, relaunch.
+tauri-plugin-updater = "2"
+tauri-plugin-process = "2"
+
+[features]
+# Used by `tauri dev`/CLI for hot-reload of the Rust side.
+custom-protocol = ["tauri/custom-protocol"]

apps/desktop/src-tauri/build.rs

@@ -0,0 +1,3 @@
+fn main() {
+    tauri_build::build()
+}

apps/desktop/src-tauri/capabilities/default.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "../gen/schemas/desktop-schema.json",
+  "identifier": "default",
+  "description": "Minimal capability set for the kiosk shell. The window only needs to render the SPA; it is granted NOTHING that touches the filesystem, shell, or devices — those stay server-side. Add a named permission here only when a concrete need arises (deny-by-default). See wiki/decisions/desktop-shell-tauri.md.",
+  "windows": ["main"],
+  "permissions": [
+    "core:default",
+    "updater:default",
+    "process:default"
+  ]
+}

apps/desktop/src-tauri/src/lib.rs

@@ -0,0 +1,21 @@
+// Parking System desktop shell — entry point.
+//
+// Intentionally minimal: build the default Tauri app and run it. The window
+// config (kiosk, fullscreen, which URL/assets to load) lives in tauri.conf.json.
+// No custom commands are registered — the renderer (the @parking/web SPA) reaches
+// the backend over HTTP to the local Fastify server, NOT through Tauri IPC. This
+// keeps the shell a thin presentation wrapper with a deny-by-default native
+// surface (see wiki/decisions/desktop-shell-tauri.md).
+
+#[cfg_attr(mobile, tauri::mobile_entry_point)]
+pub fn run() {
+    tauri::Builder::default()
+        // Auto-update: the JS side (apps/web) checks on launch, prompts the
+        // operator, and installs + relaunches on confirm. These plugins expose
+        // the update check/install and the relaunch to that flow. The updater
+        // endpoint + signing pubkey live in tauri.conf.json.
+        .plugin(tauri_plugin_updater::Builder::new().build())
+        .plugin(tauri_plugin_process::init())
+        .run(tauri::generate_context!())
+        .expect("error while running the Parking System desktop shell");
+}

apps/desktop/src-tauri/src/main.rs

@@ -0,0 +1,6 @@
+// Prevents an extra console window on Windows in release.
+#![cfg_attr(not(debug_assertions), windows_subsystem = "windows")]
+
+fn main() {
+    parking_desktop_lib::run()
+}

apps/desktop/src-tauri/tauri.conf.json

@@ -0,0 +1,50 @@
+{
+  "$schema": "https://schema.tauri.app/config/2",
+  "productName": "Parking System",
+  "version": "0.0.0",
+  "identifier": "com.parking.desktop",
+  "build": {
+    "devUrl": "http://localhost:5173",
+    "frontendDist": "../../web/dist",
+    "beforeDevCommand": "pnpm --filter @parking/web dev",
+    "beforeBuildCommand": "pnpm --filter @parking/web build"
+  },
+  "app": {
+    "windows": [
+      {
+        "label": "main",
+        "title": "Parking System",
+        "width": 1280,
+        "height": 800,
+        "minWidth": 1024,
+        "minHeight": 640,
+        "resizable": true,
+        "maximized": true,
+        "fullscreen": false
+      }
+    ],
+    "security": {
+      "csp": "default-src 'self'; img-src 'self' data: blob:; style-src 'self' 'unsafe-inline'; connect-src 'self' http://127.0.0.1:3000 http://localhost:3000 ws://127.0.0.1:3000 ws://localhost:3000"
+    }
+  },
+  "bundle": {
+    "active": true,
+    "targets": "all",
+    "createUpdaterArtifacts": true,
+    "icon": [
+      "icons/32x32.png",
+      "icons/128x128.png",
+      "icons/128x128@2x.png",
+      "icons/icon.icns",
+      "icons/icon.ico"
+    ]
+  },
+  "plugins": {
+    "updater": {
+      "endpoints": [
+        "https://UPDATES.EXAMPLE.invalid/parking/{{target}}/{{arch}}/{{current_version}}"
+      ],
+      "pubkey": "dW50cnVzdGVkIGNvbW1lbnQ6IG1pbmlzaWduIHB1YmxpYyBrZXk6IDgxNzg5RUQ1QkM0Q0FDRjYKUldUMnJFeTgxWjU0Z1RlNmhneDVZQlVVTVZZdGhJTkUxTGdDeGYwQSttZmNKVVp5WEdVMWlBb1YK"
+    }
+  }
+}

apps/desktop/turbo.json

@@ -0,0 +1,10 @@
+{
+  "$schema": "https://turbo.build/schema.json",
+  "extends": ["//"],
+  "//": "Tauri shell as a first-class Turbo node. build outputs [] so `turbo run build` doesn't try to cache/compile the Rust bundle on every pass (a real desktop bundle is a deliberate `pnpm --filter @parking/desktop build`).",
+  "tasks": {
+    "build": {
+      "outputs": []
+    }
+  }
+}

apps/web/.env.production

@@ -0,0 +1,11 @@
+# Production build env for the SPA (auto-loaded by `vite build`, which the Tauri
+# desktop bundle runs via beforeBuildCommand). NOT loaded by `vite` dev.
+#
+# The desktop shell serves the bundled SPA from tauri://localhost (no proxy, not
+# same-origin), so the SPA must reach Fastify by absolute origin. This is the
+# appliance's local Fastify address. Not a secret — committed for reproducible
+# desktop builds. Override per-deployment if Fastify binds elsewhere.
+#
+# NOTE: a plain browser prod build (Fastify serving dist/ same-origin) does NOT
+# want this set. If you build the SPA for that, override VITE_API_BASE="" .
+VITE_API_BASE=http://127.0.0.1:3000

apps/web/package.json

@@ -17,6 +17,8 @@
     "@radix-ui/react-tabs": "^1.1.15",
     "@tanstack/react-query": "^5.101.0",
     "@tanstack/react-router": "^1.170.16",
+    "@tauri-apps/plugin-process": "^2.3.1",
+    "@tauri-apps/plugin-updater": "^2.10.1",
     "i18next": "^26.3.1",
     "react": "19.2.7",
     "react-dom": "19.2.7",

apps/web/src/api.ts

@@ -6,6 +6,7 @@
 // wiki/entities/local-jwt-auth.md.
 
 import { logFailedRequest } from "./lib/logger.js";
+import { apiUrl } from "./lib/origin.js";
 import type { AppLogRecord } from "@parking/shared";
 
 const CSRF_COOKIE = "parking_csrf";
@@ -27,7 +28,7 @@ export async function apiFetch<T>(path: string, init: RequestInit = {}): Promise
     const csrf = readCookie(CSRF_COOKIE);
     if (csrf) headers.set(CSRF_HEADER, csrf);
   }
-  const res = await fetch(path, { ...init, headers, credentials: "include" });
+  const res = await fetch(apiUrl(path), { ...init, headers, credentials: "include" });
   if (!res.ok) {
     const msg = (await res.json().catch(() => ({}))) as { error?: string; problems?: string[] };
     const error = msg.error ?? `${path}: ${res.status}`;

apps/web/src/lib/desktop-updater.ts

@@ -0,0 +1,51 @@
+// Desktop auto-update — prompt-on-update flow.
+//
+// Runs ONLY inside the Tauri desktop shell; a plain browser has no updater, so
+// this is a guarded no-op there. On launch it checks the configured update
+// endpoint (tauri.conf.json → plugins.updater); if a signed newer version is
+// available it asks the operator, then downloads + installs and relaunches.
+//
+// The plugins are imported dynamically so the browser build never bundles them
+// and never tries to resolve the Tauri APIs. Offline-first: a failed check (no
+// network — the appliance is usually offline) is swallowed; updates only happen
+// when someone has brought the box online (e.g. a phone hotspot) on purpose.
+
+/** True when running inside the Tauri webview (not a normal browser). */
+function inTauri(): boolean {
+  return typeof window !== "undefined" && "__TAURI_INTERNALS__" in window;
+}
+
+export interface UpdatePrompt {
+  /** Newer version string offered by the server. */
+  version: string;
+  /** Release notes, if the server provided them. */
+  notes?: string;
+}
+
+/**
+ * Check for an update. If one is available, calls `confirm` (your UI) with the
+ * version/notes; when it resolves true, downloads + installs and relaunches.
+ * No-op (resolves silently) in the browser or when no update / offline.
+ */
+export async function checkForDesktopUpdate(
+  confirm: (info: UpdatePrompt) => Promise<boolean>,
+): Promise<void> {
+  if (!inTauri()) return;
+  try {
+    const { check } = await import("@tauri-apps/plugin-updater");
+    const update = await check();
+    if (!update) return; // up to date
+
+    const accepted = await confirm({ version: update.version, notes: update.body });
+    if (!accepted) return;
+
+    // Download + install the signed update (signature verified against the
+    // pubkey in tauri.conf.json), then relaunch into the new version.
+    await update.downloadAndInstall();
+    const { relaunch } = await import("@tauri-apps/plugin-process");
+    await relaunch();
+  } catch {
+    // Offline / endpoint unreachable / no update server yet → ignore. The app
+    // keeps running on the current version; checking again next launch.
+  }
+}

apps/web/src/lib/i18n/en.ts

@@ -38,6 +38,10 @@ export const en: Catalog = {
     signIn: "Sign in",
     signingIn: "Signing in…",
   },
+  update: {
+    available: "Update available",
+    prompt: "Version {{version}} is available. Install now and restart?",
+  },
   nav: {
     booth: "Booth",
     shift: "Shift",

apps/web/src/lib/i18n/sq.ts

@@ -40,6 +40,10 @@ export const sq = {
     signIn: "Hyr",
     signingIn: "Duke hyrë…",
   },
+  update: {
+    available: "Përditësim i disponueshëm",
+    prompt: "Versioni {{version}} është i disponueshëm. Ta instaloj tani dhe ta rinis?",
+  },
   nav: {
     booth: "Kabina",
     shift: "Turni",

apps/web/src/lib/kiosk.ts

@@ -0,0 +1,16 @@
+// Kiosk affordances for the operator console.
+//
+// We do NOT lock the operator out of the OS (that's a deliberate decision —
+// the desktop window starts maximized, not fullscreen). The one restriction is
+// blocking the right-click context menu in PRODUCTION builds, so an operator
+// can't reach "Inspect"/"Reload"/"Save as" on the live appliance. In DEV the
+// context menu (and devtools) stay available for debugging.
+//
+// Applies to both the browser prod build and the Tauri desktop build, since both
+// load this same SPA. import.meta.env.PROD is true for `vite build`, false for
+// `vite` dev.
+
+export function installKioskGuards(): void {
+  if (!import.meta.env.PROD) return; // dev: keep right-click + devtools
+  window.addEventListener("contextmenu", (e) => e.preventDefault());
+}

apps/web/src/lib/origin.ts

@@ -0,0 +1,30 @@
+// Where the SPA reaches the Fastify backend.
+//
+// In a browser (dev via the Vite proxy, or prod where Fastify serves the built
+// SPA) this is EMPTY — requests stay relative (`/api/...`) and same-origin, so
+// nothing changes. The Tauri desktop shell (apps/desktop) serves the bundled
+// SPA from `tauri://localhost`, which has no backend and no proxy; there we set
+// VITE_API_BASE to the appliance's Fastify origin (e.g. http://127.0.0.1:3000)
+// at build time so /api and the live WS feed resolve to the real server.
+//
+// Keep this the SINGLE source for the backend origin — api.ts and the live-feed
+// WebSocket both read it, so the web app and the desktop shell stay identical
+// except for this one build-time value.
+
+/** Backend HTTP origin, no trailing slash. Empty string = same-origin/relative. */
+export const API_BASE: string = (import.meta.env.VITE_API_BASE ?? "").replace(/\/$/, "");
+
+/** Resolve an API path to a full URL (or a relative path when API_BASE is empty). */
+export function apiUrl(path: string): string {
+  return API_BASE ? `${API_BASE}${path}` : path;
+}
+
+/** Build the ws:// or wss:// URL for the backend's live feed. Uses API_BASE when
+ *  set (Tauri), else the page origin (browser). */
+export function wsUrl(path: string): string {
+  if (API_BASE) {
+    return `${API_BASE.replace(/^http/, "ws")}${path}`;
+  }
+  const proto = window.location.protocol === "https:" ? "wss:" : "ws:";
+  return `${proto}//${window.location.host}${path}`;
+}

apps/web/src/lib/use-live-feed.ts

@@ -3,6 +3,7 @@ import { useQueryClient } from "@tanstack/react-query";
 import type { DeviceStatus, LedgerEvent, Occupancy } from "../api.js";
 import { qk } from "./query.js";
 import { useLiveStore } from "./live-store.js";
+import { wsUrl } from "./origin.js";
 
 // Booth WebSocket client. Opens ONE socket to /api/ws and turns server pushes into
 // (a) live-store updates for the ticker/occupancy and (b) Query cache invalidations
@@ -18,11 +19,6 @@ type WsMessage =
   | { kind: "printer-status"; event: unknown }
   | { kind: "device-status"; event: DeviceStatus };
 
-/** Build the ws:// or wss:// URL for the same origin the SPA is served from. */
-function wsUrl(): string {
-  const proto = window.location.protocol === "https:" ? "wss:" : "ws:";
-  return `${proto}//${window.location.host}/api/ws`;
-}
 
 export function useLiveFeed(): void {
   const qc = useQueryClient();
@@ -39,7 +35,7 @@ export function useLiveFeed(): void {
     const connect = () => {
       if (closedRef.current) return;
       setStatus(retryRef.current === 0 ? "connecting" : "connecting");
-      const sock = new WebSocket(wsUrl());
+      const sock = new WebSocket(wsUrl("/api/ws"));
       sockRef.current = sock;
 
       sock.onopen = () => {

apps/web/src/main.tsx

@@ -5,11 +5,23 @@ import "./lib/i18n/index.js"; // initialize i18next before the app renders
 import { App } from "./App.js";
 import { ErrorBoundary } from "./lib/ErrorBoundary.js";
 import { installClientLogging } from "./lib/logger.js";
+import { installKioskGuards } from "./lib/kiosk.js";
+import { checkForDesktopUpdate } from "./lib/desktop-updater.js";
+import i18n from "./lib/i18n/index.js";
 
 // Capture uncaught errors / rejections / console noise → backend log store, before
 // the app mounts so even an early crash is reported. See lib/logger.ts.
 installClientLogging();
 
+// Block the right-click context menu in prod builds (dev keeps it + devtools).
+installKioskGuards();
+
+// Desktop only: check for a signed update on launch and, if one exists, ask the
+// operator before installing + relaunching. No-op in the browser / when offline.
+void checkForDesktopUpdate(({ version }) =>
+  Promise.resolve(window.confirm(i18n.t("update.prompt", { version }))),
+);
+
 const rootEl = document.getElementById("root");
 if (!rootEl) throw new Error("root element not found");