Architecture remediation: 11-phase review fixes (backend + client)

[This-is-Rahul-Yadav]

Architecture remediation — 11 phases

Implements the full set of fixes from the codebase architecture review. Each phase is an atomic commit with its own detailed message; this PR is the overview. Every plan deviation is recorded in docs/architecture-remediation-plan.md.

Backend (phases 1–8)

Phase	Change
1	Centralized exception handling — one register_exception_handlers() per app maps domain exceptions to HTTP; routers raise, never build error responses. New domain exceptions replace leaked ValueError/KeyError.
2	Killed module-level singletons — 7 relay globals → a RelayState dataclass on app.state (built in lifespan); the server's process-level _stores cache → one ServerStateStore injected per app. Two apps can now coexist in one process.
3	SQLite off the event loop — service-layer store calls run via asyncio.to_thread; ShareLinkService is async; upload_index is honestly async. New shared/sqlite_kernel.py unifies the relay's aiosqlite bootstrap.
4	Tunnel protocol hardening — PROTOCOL_VERSION negotiation in the handshake (skewed agents rejected at connect), typed + size-capped RequestMetadata/WsOpenMetadata, agent-side heartbeat (detects half-dead relay sockets), guarded sends (TunnelSendError → 503 instead of crashing the proxy).
5	HTML rewriter hardening — extracted html_rewriter.py: charset-aware decode, passthrough on undecodable/oversize bodies (5 MiB cap). The proxy can no longer crash on non-UTF-8 HTML.
6	Dropbox is a first-class mount — generic LocalAsgiMount (app + client + WS bridge + lifecycle) in RelayState.local_mounts; mount_proxy has zero drop-box-specific code.
7	HMAC-signed identity headers — each agent mints a per-mount secret, shared only with this relay (handshake) and its embedded server (config); the relay signs the injected X-WFS-* identity tuple and the server verifies before trusting. Closes the LAN spoof vector. Also closed a latent hole: AuthMiddleware bypassed the password gate on a raw x-wfs-auth-bypass header without verifying the signature. AccessMode.LEGACY makes the pre-v1.3 fail-open explicit and logged.
8	Composition cleanups — server/app/bootstrap.py is the composition root (build_mount_app, run_mount_agent, run_lan_server); cli.py is parsing + delegation and no longer imports the agent. The agent's two hand-rolled receive loops are unified into TunnelConnection.run_receive_loop_with_handlers — no more poking conn._ws/_dispatch_frame.

Client (phases 9–11)

Phase	Change
9	API types from OpenAPI — server/app/openapi_dump.py + scripts/gen_api_types.sh generate client/src/types/api.gen.ts; the type modules derive from it. New CI api-types job regenerates and git diff --exit-codes — a backend schema change that isn't reflected in the client types fails the build.
10	React Query state layer + AppMode routing — BrowseProvider backs the file listing with useQuery(["files", path]); loadFiles is invalidateQueries and mutations invalidate on success (no manual-refetch race, requests dedup). resolveAppMode() + an AppMode const-object replace main.tsx's scattered routing if-chain.
11	Hard-path hook tests — the three previously-untested stateful hooks: useWebSocket (MockWebSocket + fake timers: reconnect backoff escalation, stable-connection reset, delay cap, dispatch, unmount safety), useUpload (concurrency cap, 409→conflict→SKIP/OVERWRITE, failure→retry), useClipboard (debounce coalescing, WS reconciliation, optimistic-title rollback).

Verification

• Backend: ruff ✓ · mypy --strict ✓ · 974 pytest ✓
• Client: eslint ✓ · tsc ✓ · 113 vitest ✓ · vite build ✓
• No OpenAPI drift (the new CI job passes locally).
• CI workflow updated (Node 24-native action majors; the api-types drift job added).

Notes / follow-ups (not in scope here)

• React Query is scoped to the file listing (the highest-value race); clipboard/shares/file-requests can adopt the pattern incrementally.
• The proxy's client_dist / path static lookup relies on Starlette URL normalization to block .. traversal — worth an explicit hardening pass.

🤖 Generated with Claude Code