@astralyn/sash 0.1.0

package/docs/backend.md

@@ -0,0 +1,260 @@
+# Backend Architecture & Supervisor Design
+
+Sash uses a loopback-only supervisor daemon (`sashd`) to own the Core process, generated configuration, profile state, system-proxy ownership and the HTTP/WebSocket gateway.
+
+```text
+CLI / WebUI
+    │  http://127.0.0.1:19090
+    ▼
+sashd
+├── /sash/*       daemon control, Core lifecycle, settings, profiles, system proxy
+├── /core/api/*   authenticated controller reverse proxy
+├── ProfileService
+├── RuntimeLifecycle
+│   ├── CoreSupervisor
+│   └── SystemProxyManager
+└── state locks / atomic persistence
+```
+
+The Core remains a non-detached child of `sashd`. Runtime transitions, disk mutations and daemon startup are serialized at separate boundaries instead of relying on PID files as locks.
+
+---
+
+## 1. Module Boundaries
+
+- `src/daemon.ts`: public facade re-exporting the daemon surface.
+- `src/daemon/router.ts`: the single URLPattern route table plus match → auth → dispatch; `src/daemon/handlers/*` own the per-domain handlers, `src/daemon/errors.ts` maps domain errors onto the unified error envelope, and `src/daemon/context.ts` holds the shared `DaemonContext`/`DaemonGate`.
+- `src/daemon/app.ts`: service assembly around one mutation queue; `src/daemon/server.ts` owns the HTTP/WebSocket listeners and listener close; `src/daemon/scheduler.ts` owns profile auto-update timers; `src/daemon/entry.ts` is the production entrypoint.
+- `src/runtime-lifecycle.ts`: serialized Core/proxy state transitions.
+- `src/supervisor.ts`: child ownership, readiness probes and verified termination.
+- `src/daemon-lifecycle.ts`: daemon discovery, singleton startup, CLI shutdown and the maintenance boundary used by full restarts and Core updates.
+- `src/state-lock.ts`: atomic file leases and cross-process mutation queues.
+- `src/system-proxy-manager.ts`: durable proxy ownership journal, serialized asynchronous OS operations, generation-bound observation cache and conditional recovery.
+- `src/sysproxy.ts` / `src/sysproxy/`: public system-proxy API plus focused Windows, macOS and GNOME asynchronous snapshot/apply backends.
+- `src/profile-service.ts`: profile/config preparation and publication through one-shot opaque capabilities with strict optimistic rechecks.
+- `src/core-install-record.ts`: the canonical install-record codec and release-tag validation shared by install and update paths.
+- `src/core-update.ts`: the low-level executable/install-record transaction, force-repair quarantine and crash recovery.
+- `src/core-update-coordination.ts`: one logical commit/rollback decision across retained managed state and the Core update journal.
+- `src/core-update-service.ts`: staged update, runtime ownership, maintenance, publication and restoration orchestration.
+- `src/offline-mutation.ts` / `src/runtime-recovery.ts`: daemon/offline ownership checks and the fixed legacy-proxy, journaled-proxy, stale-Core and update-recovery order.
+- `src/http.ts` / `src/github.ts`: bounded networking and trusted release downloads, including one absolute asset budget shared across mirror attempts and redirects.
+- `src/settings.ts`: versioned runtime schema, explicit public-field allowlist and candidate validation for `sash.json`.
+- `src/settings-service.ts`: shared online/offline settings preparation, durable publication and runtime-transition orchestration behind a single typed `apply(patch)` transaction.
+- `src/contracts.ts`: browser-safe API contracts and `unknown`-to-typed response parsers shared by the daemon client and WebUI.
+- `src/sash-client.ts`: browser-safe typed client for the daemon-owned `/sash/*` API, built from those parsers; `src/daemon-client.ts` is the Node factory adding retries, deadlines and loopback-only dispatch.
+- `src/runtime-owner.ts`: runtime ownership state machine and the start/stop/restart orchestration consumed by the thin `src/commands/*` wiring modules.
+- `src/json-shape.ts` / `src/error-utils.ts`: domain-neutral JSON shape, canonical timestamp and unknown-error helpers; persistent readers retain their own size, missing and corruption policies.
+- `src/status.ts`: stable CLI status/proxy observations, explicit unknown values and complete/incomplete exit semantics.
+- `src/log-follow.ts`: bounded tail/follow cursors with creation, truncation, identity-rotation and cancellation handling.
+- `web/src/stores/state.ts`: the single reactive WebUI state source, runtime ownership metadata and computed selectors. Focused runtime, profile, Core, telemetry and toast modules import it directly; `web/src/stores/index.ts` is only the stable public re-export facade.
+- `web/src/views/OverviewView.vue`: page header, Core restart and responsive two-column composition. `OverviewGeneralPane.vue` owns common controls and traffic, `OverviewProxyPane.vue` owns mode-driven groups, and `useProxyLatency()` owns generation-bound latency requests.
+
+---
+
+## 2. Ownership and Serialization
+
+### Daemon ownership
+
+`sashd` acquires `state/sashd.lock` before reading or migrating persistent state. The lock record contains a random token, PID, purpose and timestamp. A PID file is discovery metadata only; it is never the singleton authority.
+
+- `state/sashd-start.lock` serializes concurrent CLI spawn attempts.
+- `state/runtime.lock` serializes top-level `start`, `stop`, `restart` and Core update operations.
+- `state/mutation.lock` separates daemon-owned mutations from offline CLI mutations.
+- `state/settings.lock` prevents concurrent first-run secret generation and settings rewrites.
+- `state/system-proxy.json.lock` serializes proxy journal operations.
+
+Lock records are fully written and fsynced before an atomic hard-link publishes them. Synchronous and asynchronous callers share one acquisition decision and differ only in how they wait, so live-owner, dead-owner, corruption and deadline rules cannot drift. A live owner is never displaced. Dead owners can be reclaimed; corrupt records fail closed and require explicit repair. If a lock disappears between metadata inspection and bounded content read it is retried as a missing observation rather than mislabeled corrupt. Durable rename/remove operations retry Windows sharing violations without deleting a caller-owned source; an interrupted executable unlock probe is restored before Core consistency checks, while conflicting target/probe bytes are both preserved for explicit repair.
+
+Offline commands reload settings after acquiring `mutation.lock`. Ordinary mutations refuse a live orphan Core or corrupt PID record. Lifecycle and update callers must explicitly request reconciliation, which restores legacy and journaled proxy ownership before terminating only a verified stale Core and then recovering coordinated update state.
+
+CLI commands resolve one tagged runtime owner before choosing daemon or offline behavior. Only the healthy branch constructs a daemon client, and both control requests and displayed dashboard/API endpoints use the daemon's observed PID-record port rather than a potentially stale configured port. Confirmed-stopped and unresponsive owners remain distinct so an uncertain live daemon is never treated as offline.
+
+### Runtime lifecycle
+
+`RuntimeLifecycle` is the only daemon layer that combines Core and system-proxy transitions. Operations enter one promise queue and update a small phase model (`stopped`, `starting`, `running`, `stopping`, `restarting`, `failed`) with a monotonic generation.
+
+Invariants:
+
+1. A start prepares and Core-validates the exact active config before spawn.
+2. The Core must pass two readiness probes before it is considered healthy.
+3. After readiness, a bounded `/configs` probe records the actual `tun.enable` state; probe failure is represented as unknown instead of being mistaken for inactive.
+4. Desired system proxy is applied only after readiness.
+5. A deliberate stop restores the previous OS proxy before stopping the Core.
+6. If proxy restoration cannot be proved, the healthy Core is left running.
+7. Late child-exit events and delayed cleanup callbacks cannot clear a replacement child.
+8. Controller status probes retain an owned-child generation snapshot and report stopped if that child exits or is replaced while the probe is pending.
+9. System-proxy application verifies the same healthy owned child before and after OS changes; lost ownership immediately triggers proxy release.
+10. Process ownership is revalidated before every graceful or force signal; failed verification or termination preserves PID ownership.
+
+Unexpected Core exit retries proxy restoration and records failures in daemon error logs.
+
+---
+
+## 3. API Namespaces
+
+There are exactly two HTTP namespaces plus the static dashboard. Every `/sash/*` route is implemented by `sashd` itself; every `/core/api/*` route is reverse-proxied to the Core controller. There are no root-level aliases and no unprefixed duplicates.
+
+```text
+/sash/*        implemented by sashd
+/core/api/*    forwarded to the Core controller (HTTP and WebSocket share one rule)
+/ui/*          static dashboard assets
+/              302 redirect to /ui/
+```
+
+### `/sash/*`
+
+| Endpoint | Method | Auth | Description |
+| :--- | :--- | :--- | :--- |
+| `/sash/daemon/health` | `GET` | public | Readiness, PID, start time and per-boot WebUI token. |
+| `/sash/daemon/status` | `GET` | public | Daemon/Core/proxy/public-settings snapshot; `core.tunActive` is the verified runtime TUN state when available, while proxy `appliedKnown`/`stateKnown` and `queryError` preserve OS observation uncertainty. |
+| `/sash/daemon/shutdown` | `POST` | control | Under the daemon mutation queue, snapshot whether Core was running, restore proxy/stop Core, return `{coreWasRunning}`, then close. Cleanup failure returns `500` and leaves the daemon available for retry. |
+| `/sash/core/start` | `POST` | control | Rebuild config, start and wait for readiness; returns `{pid, version?, tunActive?}`. |
+| `/sash/core/stop` | `POST` | control | Restore proxy, then stop the child; `204`. |
+| `/sash/core/restart` | `POST` | control | Rebuild config and execute one serialized replacement; same body as start. |
+| `/sash/core/reload` | `POST` | control | Re-render, validate and reload active config; returns `{proxyCount, source}`. |
+| `/sash/proxy` | `GET` | public | Desired, Sash-owned and observed OS proxy state. |
+| `/sash/settings` | `GET` | public | Public settings projection (secrets omitted). |
+| `/sash/settings` | `PATCH` | control | Partial-object update (`SettingsPatch`); one transaction per apply, returns `{restartRequired, settings}`. Enabling `systemProxy` requires a healthy Core. |
+| `/sash/settings/file` | `GET` | control | Raw canonical `sash.json` text, including secrets. |
+| `/sash/settings/file` | `PUT` | control | Replace settings from raw text; parsed, diffed and applied through the same `SettingsService.apply` path. |
+| `/sash/profiles` | `GET` / `POST` | public / control | List profiles; add a remote subscription. |
+| `/sash/profiles/import` | `POST` | control | Import a local profile document. |
+| `/sash/profiles/active` | `PUT` | control | Activate a profile id or `null`. |
+| `/sash/profiles/update-all` | `POST` | control | Update every profile; always `200`, per-profile failures in `failed`. |
+| `/sash/profiles/:id/content` | `GET` / `PUT` | control | Read or replace raw profile YAML. |
+| `/sash/profiles/:id/update` | `POST` | control | Re-fetch one remote profile. |
+| `/sash/profiles/:id` | `PATCH` / `DELETE` | control | Rename or remove one profile. |
+
+Appending `?fresh=1` to status/proxy reads bypasses the short OS-state cache used by normal WebUI polling.
+
+### Response envelope
+
+Success responses return the resource body directly with no `ok` field; mutations with no content return `204`. Error responses always carry `{error: {code, message}}` where `code` is machine-readable: `invalid_input`, `not_found`, `conflict`, `core_unhealthy`, `shutting_down`, `unauthorized`, `http` or `internal`. A `500` never leaks internal error text. `update-all` reports per-profile business failures through its `failed` array at HTTP `200`.
+
+The WebUI store has one runtime-refresh path. Normal polling keeps a coherent same-owner Core snapshot until it is missing, degraded or stale for the current profile revision, while explicit post-mutation refreshes force a complete snapshot. Connections, proxies and rules use the same generation-bound fetch/adopt/error template, so responses from an older runtime owner cannot overwrite current state.
+
+The Node daemon client and browser WebUI share one browser-safe client built on `src/contracts.ts`: successful bodies are read as `unknown` and passed through per-resource parsers. Required nested fields, positive safe-integer PIDs, valid ports, nonnegative revisions, canonical timestamps, optional Core fields, proxy state and explicit public settings are validated before state changes. Unknown extra fields are tolerated for forward compatibility but discarded from the typed projection. `appliedKnown` and `stateKnown` are mandatory inside the current daemon; only the network parser normalizes flags omitted by a legacy daemon to `false`. A malformed `200` response is therefore an error, not trusted TypeScript data.
+
+### `/core/api/*`
+
+Every request in this namespace requires the persistent CLI bearer or per-boot WebUI token before an upstream connection is opened. `sashd` strips Sash credentials and the browser Host header, then injects the internal controller bearer.
+
+HTTP and WebSocket routing consume one parsed origin-form request target. Absolute-form, authority-form, asterisk-form, network-path and cross-authority backslash targets are rejected with `400`. Route matching removes only trailing route slashes; WHATWG dot-segment normalization happens once, encoded slashes are not decoded again, and the same canonical pathname constructs the Core target. In particular, `/core/api?x=1` forwards as `/?x=1`, repeated namespace-root slashes collapse to `/`, and the query is appended exactly once.
+
+Known paths with the wrong method return `405` plus an `Allow` header derived from the route table. Dashboard redirects accept only `GET`/`HEAD` and preserve the root query.
+
+Traffic/log streams are authenticated `GET` WebSocket upgrades under `/core/api/traffic` and `/core/api/logs`. HTTP and WebSocket share the same gateway rule: only `/core/api/*` is forwarded, and WebSocket upgrades only accept `GET`.
+
+---
+
+## 4. Control-Request Security
+
+- The daemon listener binds only to `127.0.0.1`, rejects non-loopback Host headers, and only accepts loopback Core controller addresses.
+- State-changing methods and every HTTP Core-gateway route require the persistent CLI bearer or per-boot WebUI token. Any request carrying a non-loopback Origin header is rejected outright, regardless of method.
+- WebSocket upgrades validate loopback Origin, authentication and route boundaries.
+- Public settings/status contracts omit controller and daemon secrets.
+- Controller and daemon clients use a direct dispatcher with normal TLS verification; proxy environment variables apply only to remote downloads.
+- Every managed runtime and OS/browser/package helper child removes GitHub/npm tokens, npm credential-file/auth variables and npm registry credentials. Fixed Windows/macOS system tools use trusted absolute paths; Linux desktop helpers are resolved only through absolute PATH entries.
+
+---
+
+## 5. Settings, Profiles and Config Transactions
+
+`sash.json` has explicit `schemaVersion: 1`. Loading validates the JSON root, every field type, nonblank control-character-free secrets, port range, loopback controller address, unknown keys and all three listener ports (`mixedPort`, controller and daemon) for collisions. Version-0 files and removed version metadata migrate to canonical v1. Invalid or future-version files are never overwritten.
+
+After managed-state recovery, daemon and offline initialization first migrate a nonblank legacy `subscriptionUrl` into an active meta-only profile. That URL has priority over any pre-profile `config.yaml`. Only when `profiles/index.json` does not exist may Sash import `config.yaml` once as the active local `Imported config` profile. A present empty index is an explicit opt-out. The candidate must be bounded, regular, valid core-format YAML and contain non-default routing content after managed operational keys are stripped: nonempty proxies/providers, or nonempty rules/groups that differ from the Sash DIRECT-only default. Exact generated defaults are not imported. Invalid candidates fail initialization without changing `config.yaml`; successful import journals the profile YAML and index under `mutation.lock` while leaving `config.yaml` byte-for-byte in place. Later `ProfileService` preparation re-renders and, when Core is installed, validates the canonical profile-derived candidate before runtime use.
+
+`SettingsService` snapshots committed settings, creates an immutable canonical candidate, then fetches/renders/Core-validates active profile configuration outside the mutation lock. Under the short commit boundary it rechecks settings/profile snapshots and journals settings plus generated config before publication. The daemon exposes only `committedSettings` to GET/status/auth handlers; Core spawn/restart can temporarily use `runtimeSettings` while a candidate transition is in progress. The committed in-memory snapshot changes only after the journaled transition succeeds; failure restores disk/config and the old runtime. Online TUN enable is additionally committed only when the restarted Core reports `tun.enable: true`; inactive or unverified results use the same disk/config/runtime compensation path. Inactive TUN errors direct every platform to rerun a full `sash restart` from an elevated shell, which replaces the daemon itself; they preserve the data root explicitly only where it was customized or `sudo` would change the default home. A Core-only restart (for example from the dashboard) cannot elevate `sashd`.
+
+Prepared profile work is never exposed as a mutable internal transaction object. `ProfileService` issues WeakMap-backed, one-shot opaque capabilities that reject forgery, cross-instance use and repeated consumption. Settings publication deliberately binds a weak active-source snapshot (`activeId`, profile identity/URL and exact raw YAML digest), so unrelated metadata updates do not invalidate an otherwise safe settings change. A strict active reload instead binds the committed settings, complete active `ProfileMeta`, active selection and raw digest. Both paths prepare outside the mutation boundary and consume the capability only while rechecking and publishing; only a conflict raised before the publication callback is entered receives the single bounded automatic retry.
+
+Profile application follows:
+
+1. Parse the untrusted source profile.
+2. Overlay Sash-owned operational keys.
+3. Write an isolated candidate.
+4. Run the installed Core with `-t -d <root> -f <candidate>`.
+5. Enter the short profile commit boundary, re-read the bounded regular index/profile files and verify the target profile identity, URL, active selection, managed-settings snapshot and exact raw-profile SHA-256 captured during preparation.
+6. Snapshot the affected fixed roles (`sash.json`, profile YAML, index and/or `config.yaml`), then atomically persist a `publishing` record in `state/managed-state-transaction.json` before publication.
+7. Ordinary settings/profile publication reloads or restarts only after every file is published, marks the journal `committed`, then clears it. The same journal can include the canonical `sash.json` snapshot. Startup finalizes a committed journal without rolling the published state back.
+8. Core update publication uses a version-3 `core-update` coordination record. After profile/index/config files publish, phase `retained` preserves their exact pre-update snapshots until the Core journal has a durable health/restoration outcome. Ordinary mutations cannot consume this retained state.
+9. On any publication or reload failure, restore every snapshot while continuing after individual restore errors, then reload the prior config when one existed. A rollback reload failure is reported explicitly. Incomplete rollback retains the journal; daemon and offline initialization recover an ordinary `publishing` journal under `mutation.lock` before reading or migrating profile state.
+
+The daemon parses profile request bodies before its mutation boundary. Remote fetch, YAML parsing, rendering and Core validation also occur before that boundary; only recheck, publication and runtime reload are serialized. Offline commands use the same split boundary after reloading settings, verifying daemon/orphan-Core ownership and migrating the legacy setting. Remote and stored profile YAML are capped at 8 MiB; `profiles/index.json` is capped at 2 MiB, and both must be regular files. Profile requests use an absolute deadline and explicit hop-by-hop redirects: HTTPS cannot downgrade to HTTP, restricted literal addresses cannot cross origins, and public origins cannot redirect to literal private/loopback targets. Scheduled network fetches use bounded concurrency; state commits remain serialized and recheck profile identity/URL and active selection before publication. Scheduler timers are retained when daemon cleanup or listener closure fails, and are cleared only after successful shutdown.
+
+---
+
+## 6. System-Proxy Ownership
+
+`settings.systemProxy` stores desired state. `state/system-proxy.json` separately records ownership:
+
+```text
+prepared:  original snapshot + intended target persisted before OS writes
+applied:   target was written and read back exactly
+restoring: restoration began and original/target-compatible partial state remains recoverable
+```
+
+All platform capture/apply work runs through asynchronous `execFile` children with the same scrubbed environment, absolute trusted-tool resolution, timeout and output bounds as other managed helpers. Commands remain explicitly sequential: Windows writes PAC/endpoints before `ProxyEnable` and awaits best-effort WinINet refresh; macOS writes data before states and turns unwanted modes off before enabling selected modes; GNOME writes every endpoint before changing `mode`. This keeps the daemon event loop responsive without weakening partial-write ordering.
+
+`SystemProxyManager` serializes inspect, apply and release operations in one in-process queue in addition to the cross-process journal lock. Every mutation invalidates a monotonic observation generation when queued and again when complete. Same-generation inspections share one in-flight capture; ordinary polling can reuse a settled short-lived cache, while a fresh read bypasses only that settled cache. Inspection compares strict journal observations before and after OS capture and retries once if another process changes or removes the journal. Unstable observations are never cached. `/sash/health` does not enter this queue, so it remains responsive while a slow OS inspection is pending.
+
+Enable flow:
+
+1. Capture all fields Sash will modify.
+2. Derive the target and persist `prepared` atomically.
+3. Re-read the OS state to detect changes during preparation.
+4. Apply and verify the target.
+5. Mark the journal `applied`.
+
+Release/recovery restores only when every managed value still equals either the original or Sash target. Before multi-field restoration Sash persists the `restoring` phase, so a crash can continue from an original/target-compatible partial state. A third-party value is never overwritten. Failed restoration retains the journal and blocks deliberate Core shutdown.
+
+Platform scope:
+
+- Windows: manual proxy, bypass list and PAC URL are managed; the legacy flat automatic-detection value is observed for status but intentionally neither written nor verified.
+- macOS: HTTP, HTTPS, SOCKS and automatic proxy URL/state for every active network service. Existing authenticated proxy settings are not taken over because credentials cannot be restored safely.
+- Linux: GNOME `gsettings` mode, automatic URL, HTTP authentication toggle and HTTP/HTTPS/SOCKS endpoints. Other desktop environments are reported unsupported.
+
+A missing journal never authorizes Sash to disable an unrelated system proxy.
+
+---
+
+## 7. Core Download and Update Trust
+
+Release identity and asset metadata come only from official GitHub endpoints. Asset mirrors are byte transports, not trust roots.
+
+- Release tags are restricted to safe path tokens.
+- Every initial/redirect URL is HTTPS and host-allowlisted.
+- Downloads are streamed with a 128 MiB archive cap and backpressure.
+- The complete archive must match the SHA-256 digest published in GitHub release metadata.
+- Extraction has a 512 MiB output cap; ZIP deflate is streamed rather than fully inflated in memory.
+- The staged executable must report the exact requested release token via `-v`.
+- The staged executable validates the freshly generated active configuration before publication.
+
+First install publishes through `state/core-install-transaction.json`: after staging has passed digest/version checks, Sash records an empty pre-install binary/metadata snapshot, publishes the executable, publishes `state/install.json`, marks the transaction `committed`, then clears it. Startup/offline recovery removes binary and metadata for an interrupted `publishing` transaction, while a `committed` marker is only cleared. Transaction JSON uses a strict fixed schema with no stored paths.
+
+Update flow downloads and validates outside runtime ownership. Once staging completes, it acquires `state/runtime.lock` before requesting the atomic maintenance shutdown snapshot and keeps that ownership through offline publication and runtime restoration. Under `mutation.lock`, Sash reloads committed settings, performs legacy/journaled proxy cleanup and verified stale-Core cleanup once, recovers earlier update state, prepares the active profile outside the short commit boundary, then rechecks both the profile capability and controller vacancy before publication.
+
+The final mutation first writes a retained managed-state journal for profile/index/config snapshots, then starts `state/core-update-transaction.json`. Normal updates use the version-1 `prepared`, `swapped` and `health-verified` phases. A previously running Core is verified immediately; a stopped Core remains in `swapped` with the old install record and `.bak` until its next managed start proves the target controller version and health. Successful external restoration marks managed state committed before removing the Core rollback slot, so a crash cannot lose both rollback directions. Failure restores managed state before binary/install metadata and still attempts both sides if either rollback reports an error.
+
+Forced repair uses the version-2 `repair-prepared` and `repair-restoring` phases in addition to the normal swap/health phases. Malformed executable and install-metadata entries are moved to fixed `.repair.bak` quarantine paths only after the journal is durable. Partial quarantine and partial restoration are resumable. Missing, extra or unowned quarantine entries fail closed. Daemon startup and offline commands use the same proxy, stale-Core and coordinated-journal recovery order before ordinary consistency checks.
+
+Official digest metadata is mandatory. If the metadata API is unavailable, Sash refuses an unverifiable mirror download instead of falling back to executing unverified bytes.
+
+---
+
+## 8. Persistence Safety
+
+Atomic state writes use a same-directory temporary file, file `fsync`, rename and POSIX parent-directory `fsync`. Sensitive files use mode `0o600` on POSIX. Important files are:
+
+- `sash.json`: versioned desired settings and local secrets.
+- `profiles/index.json`, `profiles/<id>.yaml`: profile metadata/content.
+- `config.yaml`: runtime config rendered from the active profile or the DIRECT-only default; a qualifying pre-profile file is preserved during its one-time local-profile import.
+- `state/sash.pid`, `state/sashd.pid`: discovery records.
+- `state/system-proxy.json`: durable proxy ownership transaction.
+- `state/managed-state-transaction.json`: recoverable settings/profile/index/config snapshots, including retained Core-update coordination state.
+- `state/install.json`: committed Core version metadata using the shared fixed-shape install-record codec.
+- `state/core-install-transaction.json`: strict first-install publication journal.
+- `state/core-update-transaction.json`: strict version-1 update journal or version-2 force-repair quarantine journal, including deferred managed-start rollback ownership.
+- `state/*.lock`: local-filesystem ownership records.
+
+`SASH_HOME` should reside on a local filesystem that supports atomic rename, hard links and normal per-user permissions.

package/docs/frontend.md

@@ -0,0 +1,125 @@
+# Frontend Architecture & WebUI Design
+
+The WebUI is a Vue 3 application built with Vite and bundled into `dist/ui/`. sashd serves it at `http://127.0.0.1:19090/ui/`; `<root>/ui/index.html` can override the bundled dashboard.
+
+---
+
+## 1. Build and Quality Gates
+
+- `npm run build:ui` calls the Vite Node API through `scripts/build-ui.mjs`.
+- `npm run typecheck:web` runs `vue-tsc`, including Vue templates.
+- `npm test` runs server type checking, WebUI type checking, backend tests and WebUI TypeScript tests.
+- Biome checks WebUI TypeScript and Vite configuration. Vue templates are type-checked by `vue-tsc` and compiled by Vite.
+- Vite 6 builds the bundled dashboard on the declared Node.js 24 baseline.
+- CI runs lint, server/WebUI type checks, all tests, production builds and actual tarball pack/install/CLI/UI smoke on Windows, macOS and Linux with Node.js 24.
+
+---
+
+## 2. Source Layout
+
+```text
+web/src/
+├── api/index.ts                  typed REST client and WebSocket reconnect logic
+├── components/
+│   ├── AppSidebar.vue
+│   ├── ConfirmDialog.vue
+│   ├── Icon.vue                  semantic icon wrapper
+│   ├── icons.ts                  tree-shaken Remix Icon component mapping
+│   ├── ProxyGroupSection.vue     reusable group header/node grid
+│   ├── TrafficChart.vue
+│   └── ...
+├── i18n/                         Chinese source messages and typed English mirror
+├── stores/index.ts               runtime state, refresh actions and polling
+├── stores/state-ownership.ts     pure generations, cleanup and sync helpers
+├── styles/main.css               design tokens and shared utility/component styles
+├── types/index.ts                core-controller response types; daemon types are shared
+├── views/
+│   ├── OverviewView.vue          status, traffic, modes and proxy groups
+│   ├── ProfilesView.vue          download/import/update/select/delete profiles
+│   ├── LogsView.vue
+│   ├── ConnectionsView.vue
+│   ├── RulesView.vue
+│   └── SettingsView.vue
+├── App.vue                       shell, view selection and stream lifecycle
+├── theme.ts                      persisted system/light/dark theme state
+└── router.ts                     small hash router
+```
+
+The shell follows a classic compact desktop-console layout: a 25px title strip sits above a 170px text-navigation sidebar with live traffic, recessed active-item geometry, runtime and Core status. Below 900px it becomes a compact title strip plus safe-area-aware bottom navigation. Light and Dark themes use flat neutral surfaces, dense rows, restrained shadows and distinct mode/semantic state colors. Profiles use a full-width download toolbar and compact profile grid; Logs use an edge-to-edge stream; Connections use colored metadata tags; Settings use labeled flat sections. Overview intentionally remains a roughly one-third/two-thirds combined General + Proxies workspace: common runtime controls and the GLOBAL/RULE/DIRECT selector stay on the left while the mode-driven proxy groups or DIRECT state render on the right. `styles/main.css` owns theme tokens, component states and reduced-motion behavior without a runtime-loaded UI dependency. Functional icons use selected, tree-shaken `@remixicon/vue` line components behind the local semantic `Icon.vue` API; the Sash brand mark remains project-owned. `THIRD_PARTY_NOTICES.md` records the bundled Vue MIT and Remix Icon notices, and the complete Remix Icon License v1.0 remains in `docs/remix-icon-license.txt`; both are included in the npm tarball. Long connection and rule sets remain paginated and switch to narrow-screen layouts.
+
+Daemon/profile contracts live in `src/contracts.ts` and are imported as types by both `src/daemon-client.ts` and the WebUI. This prevents manually duplicated `SashStatus` and profile response shapes.
+
+---
+
+## 3. Runtime State Ownership
+
+`web/src/stores/index.ts` owns status, profiles, proxy groups, rules, connections, traffic history, manual delay results, logs, operation flags and toasts. Pure ownership/generation helpers live in `web/src/stores/state-ownership.ts` and are covered by browser-free `node:test` tests. A pinned `happy-dom` dev dependency supplies the minimal DOM behavior harness for mounting a real Vue `createApp` render path and asserting reactive notice transitions; no second test runner or coverage-only gate is introduced.
+
+Canonical actions include:
+
+- `refreshStatus()`
+- `refreshConnections()`
+- `refreshProxies()`
+- `refreshProfiles()`
+- `refreshRuntimeState()`
+- profile mutation actions such as `updateProfile()` and `activateProfile()`
+- runtime intent actions such as `setOutboundMode()` and `selectGroupProxy()`
+- `startRuntimePolling()`
+
+Polling is self-scheduling with `setTimeout` after the previous cycle completes. It slows to a 15-second interval while the page is hidden and refreshes immediately after returning to the foreground. Domain request generations discard responses made stale by a newer refresh or user mutation. Core-specific API calls are made only after status reports `running && healthy`.
+
+Daemon reachability, profile revision and Core snapshots have separate ownership. A successful `/sash/status` keeps the daemon online even when a downstream Core gateway request returns 502. Profiles track their last fetched daemon revision independently and refresh on revision changes even while Core is stopped. A daemon restart resets that revision comparison.
+
+The Core owner is the daemon boot plus Core PID/start time. A stopped/unhealthy Core or unreachable daemon clears proxy groups, rules, connections/totals and traffic rates/history. A same-owner Core API failure preserves the last complete configs/proxies/rules/connections snapshot, marks it degraded and retries; a changed owner clears the old snapshot before fetching, so failed replacement data cannot be shown under the new owner. Profile revision changes request a new snapshot without prematurely discarding same-owner data.
+
+Manual latency results are stored separately from polled proxy payloads. Normal proxy polling therefore preserves a test result; a successful profile snapshot generation or Core owner change invalidates stale delay results.
+
+Views call store actions rather than maintaining separate copies of status/proxy/rule refresh orchestration. Same-domain controls use store operation flags, while independent group/node latency tests remain concurrent.
+
+---
+
+## 4. Profiles and Overview Components
+
+The Profiles page provides:
+
+- URL download and clipboard paste
+- local YAML import
+- Update All and per-profile update
+- active profile selection
+- quota/expiry display from provider metadata
+- persisted update errors
+- delete confirmation
+
+The Overview proxy panel uses `ProxyGroupSection.vue` for manual, automatic and GLOBAL groups. This keeps node-card rendering, delay labels, UDP/current markers and group test controls in one component. Group and node latency tests track independent in-flight sets, so tests for different groups/nodes can run concurrently. Mode and proxy-selection mutations are latest-request-wins and disable only their matching control domain.
+
+System proxy controls are target-state based: enabling requires a running, healthy Core; disabling remains available when desired/applied/OS-observed state indicates cleanup may still be required, including while the Core is stopped.
+
+---
+
+## 5. API and Streaming
+
+`web/src/api/index.ts`:
+
+- distinguishes JSON and `204 No Content` endpoints through overloads rather than `undefined as T`;
+- reads an error response body once and surfaces JSON or plain-text messages;
+- parses WebSocket frames separately from consumer callbacks, validates finite non-negative traffic counters and known textual log records, and silently drops malformed frames;
+- maintains at most one reconnect timer per stream;
+- binds stream callbacks to the current runtime generation and stops stream ownership when the daemon session or healthy Core is unavailable;
+- resets stale traffic rates/history when the current traffic stream disconnects without allowing an older socket's close event to clear a replacement stream;
+- sends `X-Sash-Token` on HTTP requests after initialization.
+
+Streams:
+
+- `api.connectTraffic(callback)` → `/core/api/traffic`
+- `api.connectLogs(callback)` → `/core/api/logs`
+
+The controller secret is never available to browser code; sashd injects it server-side.
+
+---
+
+## 6. Interaction State
+
+- Settings derive mixed-port dirty state by comparing the draft with the last committed value, preserve a genuinely edited draft across polling, and expose an explicit reset action. Successful `allow-lan` and TUN responses commit the returned settings snapshot directly before any follow-up refresh. TUN controls separately derive active, inactive, unverified, pending-start and desired/runtime-mismatch presentation from `settings.tun` plus `core.tunActive`; failed online activation never advances the committed switch, and the returned error explains that the whole Sash daemon—not only its Core child—must be restarted with elevated privileges.
+- Logs receive monotonic IDs before entering the capped 600-row buffer, providing stable Vue keys and an update sequence even when length remains constant.
+- The global confirm service settles a previous pending Promise before opening another dialog; Escape, route changes and component unmount cancel the active confirmation.
+- The global banner distinguishes an unreachable daemon from a degraded same-owner Core snapshot and an unavailable new-owner snapshot.

package/docs/remix-icon-license.txt

@@ -0,0 +1,186 @@
+Remix Icon License v1.0
+Version 1.0 – January 2026
+Copyright (c) 2017–2026 Remix Design
+
+   This License governs the use of the Remix Icon library, including all icons,
+   SVG files, font files, and related assets (collectively, the "Icons").
+
+1. Grant of License
+
+   Subject to the terms and conditions of this License, Remix Design grants you
+   a worldwide, royalty-free, non-exclusive license to use, copy, modify,
+   merge, and distribute the Icons, as permitted below.
+
+2. Permitted Uses
+
+   You are permitted to:
+
+   2.1 Commercial and Non-Commercial Use
+       Use the Icons in personal, commercial, and client projects, including
+       but not limited to:
+       - Websites, web applications, and mobile applications
+       - Software products and SaaS platforms
+       - User interface designs, design systems, and UI kits
+       - Presentations, documentation, and marketing materials
+       - Physical or digital products where the Icons are decorative or
+       functional elements
+
+   2.2 Modification and Derivative Works
+       - Modify, adapt, or customize the Icons
+       - Change colors, sizes, stroke styles, or other visual attributes
+       to fit your project needs
+
+   2.3 Distribution as Part of a Larger Work
+       Include the Icons (modified or unmodified) as part of a larger product,
+       provided that:
+       - The Icons are functional or decorative components of the product, and
+       - The Icons are not marketed or sold as the primary value of the product
+
+   2.4 Attribution (Optional)
+       Attribution to Remix Icon is appreciated but not required.
+       Suggested attribution:
+       "Icons by Remix Icon (https://remixicon.com)"
+
+3. Restrictions
+
+   3.1 Prohibited: Standalone Icon Sales
+       You may NOT:
+       - Sell, sublicense, or distribute the Icons as a standalone product
+       - Package the Icons as an independent icon pack, icon library, or
+       icon font for sale
+       - Offer the Icons as a downloadable asset collection where the Icons
+       themselves constitute the primary product value
+
+       Clarification:
+       A product is considered a prohibited standalone icon sale if:
+       - The Icons are the primary advertised feature, or
+       - Removing the Icons would eliminate the core value of the product
+
+       Examples:
+       - Prohibited: "Premium Icon Pack – 2,000+ Icons for $29"
+       - Prohibited: "Extended Remix Icon Library (Paid)"
+       - Permitted: Website or app templates that include Icons as UI elements
+       - Permitted: Design systems or UI kits where Icons are a minor component
+
+   3.2 Prohibited: Competing Icon Libraries
+       You may NOT use the Icons to create, distribute, or sell a competing
+       icon library or icon set, even if the Icons are modified with only
+       minor or superficial changes (such as color, size, stroke width,
+       corner radius, or layout).
+
+   3.3 Prohibited: Logo, Trademark, and Brand Identity Use
+       You may NOT use the Icons, whether modified or unmodified, as:
+       - A logo, trademark, or brand identifier
+       - The primary visual identity of a company, product, or service
+
+       This includes, but is not limited to:
+       - Creating a logo by applying simple modifications such as color changes,
+       rotation, combination, or layout
+       - Using an Icon as a brand mark, app icon, or identity symbol where the
+       Icon itself represents the brand
+
+       Rationale:
+       Remix Icon is designed for functional and informational use. Using the
+       Icons as brand identifiers may impair their recognizability and neutrality
+       in other functional contexts.
+
+4. Brand Icons and Trademarks
+
+   Some Icons represent third-party brands or services.
+
+   4.1 Permitted Use of Brand Icons
+       You may use brand icons solely to represent or link to the corresponding
+       brand, product, or service.
+       Examples:
+       - Using a GitHub icon to link to a GitHub repository
+       - Displaying social media icons in a website footer
+
+   4.2 Prohibited Use of Brand Icons
+       You may NOT:
+       - Use brand icons as your own logo or trademark
+       - Modify brand icons to create a new brand identity
+       - Use brand icons in a way that implies endorsement or affiliation
+       by the brand owner
+       - Use brand icons for purposes unrelated to the represented brand
+
+   4.3 Trademark Responsibility
+       All brand icons are subject to the trademark rights of their respective
+       owners. This License does not grant any trademark rights.
+       Users are responsible for ensuring that their use of brand icons complies
+       with applicable trademark laws.
+
+5. Copyright and License Notice
+
+   When distributing the complete Icon library or substantial portions thereof:
+
+   - You must retain existing copyright notices in source files
+   - You should include a copy of this License or a link to it
+
+   For individual use of Icons within projects (e.g., compiled apps, websites,
+   presentations), no copyright notice is required.
+
+6. No Trademark Rights
+
+   This License does not grant permission to use:
+
+   - The "Remix Icon" name, logo, or trademarks
+   - Any trademarks represented by brand icons
+
+   You may refer to Remix Icon by name solely for attribution purposes.
+
+7. Disclaimer of Warranty
+
+   THE ICONS ARE PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+   IMPLIED, INCLUDING BUT NOT LIMITED TO WARRANTIES OF MERCHANTABILITY,
+   FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT.
+
+8. Limitation of Liability
+
+   IN NO EVENT SHALL REMIX DESIGN BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER
+   LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING
+   FROM, OUT OF, OR IN CONNECTION WITH THE ICONS OR THEIR USE.
+
+9. License Compatibility
+
+   You may integrate the Icons into projects under permissive licenses
+   (such as MIT, BSD, or Apache 2.0), provided that:
+
+   - The Icons themselves remain governed by this License
+   - The restrictions in Section 3 continue to apply
+
+   This License may be incompatible with licenses that require unrestricted
+   redistribution of assets as standalone products or mandatory application
+   of strong copyleft or share-alike terms.
+
+10. Termination
+
+   Your rights under this License terminate automatically if you breach its
+   terms.
+
+   Upon termination:
+
+   - You must cease any distribution that violates this License
+   - You may continue to use the Icons in projects already distributed
+   prior to termination
+   - End users who received such projects are not affected
+
+11. License Versioning
+
+   Remix Design may publish revised versions of this License.
+
+   You may choose to use the Icons under:
+
+   - The version of this License under which you received them, or
+   - Any later version published by Remix Design
+
+   Once chosen, that version may be used indefinitely.
+
+How to Apply This License
+
+   Include the following notice in your documentation when appropriate:
+
+   "This project uses icons from Remix Icon (https://remixicon.com),
+   licensed under the Remix Icon License v1.0."
+
+   When distributing the complete Icon library or substantial portions of it,
+   include a copy of this License.