feat(hosts): add per-host Web Endpoints (direct or SSH-tunnelled web UIs) - #1416
Open
nasif-naseef wants to merge 12 commits into
Open
feat(hosts): add per-host Web Endpoints (direct or SSH-tunnelled web UIs)#1416nasif-naseef wants to merge 12 commits into
nasif-naseef wants to merge 12 commits into
Conversation
jsdom in this project ships without a localStorage global, so every suite that touched storage threw "Cannot read properties of undefined" during setup and failed wholesale -- 119 tests across 15 files, none of them actual product defects. Node only supplies localStorage with --localstorage-file, which persists to disk and is shared across test files. A per-process in-memory Storage is what tests want, so define one (plus sessionStorage) when the global is absent, alongside the existing matchMedia shim. Full suite goes from 15 failed files / 119 failed tests to 400 files and 2888 tests passing. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Fdjjsdaz6aFMyJr4h3Y6qj
First step of per-host Web Endpoints: a host declares web UIs it serves and opens them either directly at the host's address or through an SSH forward Termix establishes on demand. This commit is pure logic with no I/O, so it needs no mocks to test. resolveWebEndpointUrl expects an already-normalized path -- normalization is the storage boundary's job (a later commit), and duplicating it here would invite the two copies to drift. separatedTunnelHost is the one part that is a security control rather than a convenience. Cookies are keyed by host and ignore the port, and SameSite computes "site" as scheme + registrable domain -- also ignoring the port. A forward reached at the host string serving Termix is therefore same-site with Termix, which leaks the session both ways: the framed service receives the jwt cookie, and a Set-Cookie it returns lands in the jar Termix's own API calls read from. So a tunnel URL resolves to a different loopback spelling than the page's, and refuses outright when no alias exists. Only loopback literals qualify -- a same-registrable-domain alias could still answer Set-Cookie with a Domain attribute that reaches Termix. The cookie-separation tests were verified to fail against a resolver that returns the page host (4 failures), so they cannot pass vacuously. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
normalizeWebEndpoints is the enforcement point for values that reach an href
and an iframe src, so the editor's constraints are UX rather than security.
It drops any row it refuses instead of rejecting the whole host -- one bad
endpoint must not make a host unsaveable or unlistable.
Paths are checked for C0 controls and DEL by codepoint rather than by regex
character class: "\t//evil.example" defeats a startsWith("//") guard, because
the browser strips the control character and then follows the authority.
bindHost lands both in a TCP listener and in a URL authority, so it is
restricted to a bare host literal -- nothing carrying a scheme, port, path or
credentials survives. bindHost and localPort are ignored on a direct endpoint,
which never creates a forward.
parseWebUiConfig never throws. A malformed stored value yields an empty
endpoint list, so a half-written config cannot take out the whole host
listing -- which is what dockerConfig's bare JSON.parse does today.
The editor validator is a second implementation in a layer that cannot import
backend route modules. Its accompanying test runs BOTH implementations over
the same path and port samples, because drift here is invisible in the worst
way: the editor accepts a row, the normalizer silently drops it, and the
endpoint disappears on reload with no error. That agreement test was verified
to fail (4 cases) when the editor's control-character check is removed.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Running `npm run schema:migrations` on an UNCHANGED schema emits these, so they are pre-existing drift between schema.ts and drizzle/, not something this branch introduced. Landing them alone, before the web-endpoint columns, so the feature's own migration is reviewable without an unrelated table rebuild sitting in the middle of it. Both forms are a foreign-key constraint rename only. Postgres drops and re-adds the constraint under a shorter name. SQLite has no ALTER for that, so drizzle emits the standard table rebuild -- verified data-preserving: CREATE lists 14 columns, INSERT...SELECT copies the same 14 in the same order, and both indexes are recreated. The SQLite file is in practice dead code: runRemoteMigrations throws for sqlite, which builds its schema from db/index.ts instead. It is kept rather than hand-trimmed because drizzle derives the meta snapshot from schema.ts regardless, so trimming the .sql while the snapshot advances would make the drift permanently invisible -- no future `generate` would re-emit it. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Two columns on ssh_data mirroring the Docker pair. No show_web_ui_in_sidebar: every existing showXInSidebar column is vestigial -- they appear only in defaults, the export payload and tests, and gate no rendering -- so a fourth dead column plus a migration buys nothing. web_ui_config stores an object rather than a bare array so host-level web settings can be added later without a second migration. The column has to be declared in FOUR places, not one. SQLite never runs the drizzle migrations at all (runRemoteMigrations throws for sqlite), so the live default-dialect schema comes from hand-written DDL: 1. db/schema.ts, then the two generated dialect schemas and the migrations 2. db/index.ts CREATE TABLE -- fresh databases 3. db/index.ts addColumnIfNotExists -- existing databases 4. database.ts CREATE TABLE and its positional INSERT -- encrypted export Missing 2 or 3 breaks every host write on the default dialect while the migration file sits there looking correct. Two guards, both watched failing first. bootstrap-matches-schema-columns boots a real database and compares PRAGMA table_info against the drizzle definition for every table -- it reported ssh_data.enable_web_ui and ssh_data.web_ui_config missing before item 2/3 landed. A grep-based guard could not: db/index.ts names columns as snake_case strings, never the camelCase the schema uses. export-ddl-matches-schema-columns covers database.ts, which no booted database reaches. It caught a real defect while being written: the two new columns went into the INSERT list but the VALUES list still held 53 placeholders for 55 columns. Being positional, that shifts every later value by one. The placeholder-count assertion is now permanent. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…aths A host field has to be enumerated by hand in nine places here, and "added a column, missed one update path" is this codebase's most repeated bug -- during the first attempt at this feature a field was missed at one of these points six separate times, each surfacing as a different mystery: endpoints that saved but never appeared, config that vanished on reload. Backend: host-normalizers (input type, CONNECT_LEVEL_FIELDS, boolean normalization, parse block), host.ts (create, update, both read paths, quick-connect defaults), host-bulk-routes (bulk update, import, reset). Renderer: host-export-payload, HostManagerData's sshHostToHost, tabUtils' hostToSSHHost, HostEditorData's form seed and payload builder. The three renderer mappers copy field by field, so an unlisted field is silently dropped -- which is how endpoints saved correctly and never appeared. webUiConfig is parsed with parseWebUiConfig rather than a bare JSON.parse. dockerConfig on the adjacent line uses a bare one, so a single malformed value takes out the whole host listing; that is a bug to avoid copying, not a convention to follow. All three write paths now clear webUiConfig when the feature is disabled. They disagreed before, and the export payload ships the config unconditionally -- so a host disabled without clearing still exported its endpoint list (internal hostnames, ports, paths) while the UI read as off, and re-enabling resurrected stale endpoints. webUiConfig is shared with connect-level recipients, unlike dockerConfig. A connect-level recipient is already authorized to open these tunnels, so withholding the config only breaks discovery while the flag advertises the feature. Docker's precedent does not transfer: its tab works without its config, whereas a web endpoint IS its config. The enumeration guard asserts every one of the nine files mentions the web endpoint field beside its Docker counterpart, and checks the Docker anchor is present too so it cannot pass vacuously if a file is restructured. The clear-on-disable assertion was rewritten after the first version passed with the guard deleted -- a loose regex matched unrelated sites. Both halves are now anchored on exact text and were watched failing. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
… web: Three changes the web endpoint open route depends on, plus the name reservation that makes the scheme safe. Real bound port. Under sourcePort 0 the kernel assigns the port, but the runtime recorded the requested value -- so it advertised 0 and any caller reusing it failed. It now records tcpServer.address().port. Idle close, behind the new tunnelConfig.idleTimeoutMs. Web endpoint tunnels are opened on demand and must not outlive their use. The timer lives inside establishDirectTunnel because the socket set is only visible from that closure, polls at min(30s, timeout) so "empty for N" means roughly that rather than "empty at the instant of one N-spaced tick", and unrefs so it cannot hold the process open. It calls cleanupTunnelResources rather than close(): close() stops the listener but leaves the entry in activeTunnelRuntimes, so the open route would keep handing out a port nothing is listening on. Reserved names skip retry. handleDisconnect returns early for a "web:" name after a forced cleanup. maxRetries: 0 would NOT achieve this -- the retry path reads `maxRetries || 3`, so 0 falls through to 3. The cleanup is forced because cleanupTunnelResources no-ops while tunnelConnecting holds the name, and a web tunnel has no retry pass to self-heal a leaked runtime. That early return carries an identity guard, which is the subtle one. sourceClient.end() only STARTS an async teardown, so the SSH "close" event lands after a reopen may already have registered a NEW runtime under the same name. Acting by name alone would tear down the successor rather than the stale tunnel -- surfacing as a 200 with a good port followed by a silent connection reset and no error anywhere. handleDisconnect now takes the closing Client and returns early when the registered runtime belongs to someone else. The idle timer carries the same guard for the same reason. /ssh/tunnel/connect now rejects a user-supplied "web:" name with 400. validateTunnelConfig is no defence here: it returns true unconditionally for any name that is not the legacy 6-part format, so an authenticated user could otherwise create a real retry-configured tunnel that collides with a live web endpoint forward and silently loses its own reconnect behaviour. The manager tests run against a real TCP listener and real timers -- mixing fake timers with real socket I/O is a known route to a hanging test. Both were watched failing: reverting the bound port fails the port test, and swapping cleanupTunnelResources for close() fails the idle test, which asserts the ENTRY is gone rather than merely that the listener stopped. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
POST /ssh/tunnel/web-endpoint/open { hostId, endpointId } -> { port }.
The host is resolved through the user-scoped resolveHostById, so an
authenticated user cannot obtain a forward to a host id they do not own. The
endpoint is re-normalized out of storage rather than trusted: the stored value
predates any later tightening of the rules, and this is what a forward gets
built from. An enabled flag is required as well as a present endpoint -- a
bulk update that sends only { webUiConfig } can leave a configured endpoint on
a host whose UI reads as off everywhere.
Not gated to the desktop. The forward binds wherever this backend runs, as the
server tunnels feature does, and the endpoint's own bindHost decides whether
that is reachable from a browser.
endpointHost: "127.0.0.1" is load-bearing, not cosmetic. connectSSHTunnel
picks its strategy via shouldEstablishDirectTunnel -> isSingleHostTunnel, which
keys on endpointHost -- setting only targetHost selects a different path and
the forward never binds locally.
connectSSHTunnel never rejects, and its promise resolves right after
conn.connect() -- long before the SSH "ready" event populates
activeTunnelRuntimes. Awaited is not connected, so waitForTunnelSettled polls
the maps the manager already exports. Polling rather than adding a
promise-returning variant: every existing caller is fire-and-forget by design,
and changing that contract for one new caller is the larger blast radius.
A probe forwardOut runs before returning 200. Without it the route succeeds the
moment listen() does, and forwardOut is only attempted per inbound socket where
failure is swallowed -- so the likeliest real error, nothing listening on the
endpoint's port, reached the user as a blank frame and no message.
Staleness is validated at open, never on save: host save lives in the database
service and the runtimes live in the tunnel service, with no push between them.
On reuse the route compares a fingerprint covering the endpoint's target AND
the host's SSH identity, and reopens when it differs. An absent fingerprint
means reuse, not staleness -- a reserved-prefixed runtime can only have been
created here. Deletion, disabling and host removal then need no handling:
nothing reopens the tunnel, so it idles out.
Also closes an authorization gap this feature would otherwise have created.
/ssh/tunnel/disconnect and /ssh/tunnel/cancel checked ownership only inside
`if (config && config.sourceHostId)`, and web tunnels are deliberately absent
from tunnelConfigs -- so the check never ran for them. Host ids are small
sequential integers and endpoint ids are client-supplied, so the name is
guessable and any authenticated user could force-close another user's tunnel.
authorizeTunnelAction recovers the host id from the name and fails closed when
it cannot; the tests were watched failing against the old behaviour.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…llowance
The client posts a path relative to tunnelApi's base, which already includes
/ssh -- a leading "/ssh" here resolves to /ssh/ssh/... and 404s on every call.
The test asserts that on the captured runtime argument rather than by scanning
source, so quoting style and indirection cannot fool it.
Backend error messages are preserved rather than collapsed. 502 is this
route's likeliest real failure and carries the actionable cause -- SSH auth
rejected, host unreachable, nothing listening on the target port -- and
handleApiError would replace all three with "Server error occurred". It stays
as the fallback for bodies that carry no string reason, so a body shaped
{ error: <object> } cannot reach the user as "[object Object]".
openWebEndpointExternally applies the same refusal gate as the embedded tab.
Opening in the real browser is not the safer path: the cookie jar is the
browser's either way, so a tunnel URL on the page's own host string leaks the
session exactly as a frame would. The refusal happens before the forward is
opened -- binding the port and then declining to navigate would be no
protection.
Certificate allowance covers the one case Electron's existing handling misses:
direct access to a HOSTNAME over https. isPrivateNetworkHost matches IP
literals only and sshData.ip has no IP validation, so https://nas.local:8006
fails the check and renders blank inside an iframe with no click-through --
Chromium offers no proceed option for subframes.
Three properties of that allowance are deliberate and now pinned by tests,
because each would otherwise be undone by a reasonable-looking simplification:
- it is NOT wired into isInvalidCertificateAllowedForUrl, which also governs
this process's own outbound TLS via getTlsVerificationOptions;
- it is https-only, in both the check and the IPC handler, since a non-TLS
origin in a TLS-error allowlist is meaningless and file:/ftp: must never
be storable; and
- entries carry a five-minute TTL refreshed on each registration. Main has
no host-database access and cannot verify the renderer's claim that an
origin is a configured endpoint, so the residual risk has to be a
momentary window rather than one lasting until the app restarts.
The handler stores the parsed origin, never the caller's string, so a path or
wildcard cannot widen the allowance.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Mounted as a Web UI sub-tab inside the SSH group, beside Docker, Tunnels,
Files and Host Metrics, and laid out as two SectionCards following the tunnels
editor: settings first, then the list it governs.
There is a deliberate asymmetry with the sidebar here. The sidebar entry will
appear on enableWebUi alone, because a direct endpoint needs no SSH -- but Web
UI is an SSH sub-tab, so a host with SSH disabled cannot configure endpoints at
all. That is the accepted behaviour and both halves are pinned by tests, so
neither gets "fixed" into agreement later.
tunnelAvailable is enableSsh && originIsLocal, resolved inside HostWebUiTab
rather than in HostEditor.tsx, which is already ~2600 lines. It is NOT gated on
isElectron(): the forward binds wherever the backend runs, exactly as the
server tunnels feature does. resolveConnectionOrigin is called with
connectionType "ssh" deliberately -- a tunnel endpoint always rides SSH, and
"ssh" avoids the guacamole special case that forces "remote" for
RDP/VNC/Telnet.
Three input details that each prevent a silent data loss:
- the id generator falls back off crypto.randomUUID, which is undefined
outside a secure context -- a plain-http web deployment is a first-class
target for direct+external and would otherwise throw on "Add endpoint";
- a new row gets a de-duplicated label, since labels are what identify an
endpoint in the sidebar picker; and
- the port field commits only a value the normalizer would keep. Number("")
is 0, which the normalizer rejects, so clearing the field would otherwise
write an endpoint that vanishes on save with no error.
The tunnel fields carry three warnings: a non-loopback bind exposes the
target's web UI unauthenticated to anyone who can reach the port; a loopback
bind on a remote backend cannot be reached from a browser at all; and a tunnel
reached at Termix's own hostname would hand the tunnelled service this
session. All three are shown while configuring rather than only when the tab
fails to load.
The unavailable-tunnel reason is shown whenever tunnelling is unavailable, not
only once a row asks for it -- a disabled dropdown option with no stated reason
reads as the control being broken.
Copy is reused verbatim from the previous iteration's reviewed strings rather
than reworded.
One test was written and then removed rather than kept: its name promised that
switching to tunnel access clears ignoreCert, but Radix Select needs pointer
APIs jsdom lacks, so the body only asserted the control existed. The clearing
is covered where it is enforced, in the normalizer.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
One sidebar entry per host, never one per endpoint: a host may declare up to
16, and a row of 16 identical globes is unusable. With a single endpoint the
entry wears its label and acts directly; with several it carries no endpointId
and the click opens a picker -- a DropdownMenu in the tray, a DropdownMenuSub
in the Connect submenu.
The entry is gated on enableWebUi ALONE, unlike every neighbouring action,
which requires enableSsh. A direct endpoint needs no SSH; SSH matters only
per-endpoint, for tunnel access, which the open route enforces.
openTab gains a fourth optional parameter rather than overloading `restore`,
which means something else. What was actually broken for two endpoints on one
host was the LABEL -- tab ids are already `${name}-${type}-${Date.now()}`, so
they never collided. All existing call sites keep working.
The tab is passed the endpoint ID, not the endpoint object, so one deleted
while its tab is open renders a plain message instead of throwing.
Reload re-resolves and REMOUNTS. A direct endpoint's URL never changes and a
live tunnel returns the same port on every open, so setUrl(resolved) would be
a same-value setState that React bails out of, leaving the frame untouched --
Reload would silently do nothing in the two most common cases. A generation
counter folded into the iframe key fixes that and doubles as the staleness
guard for two resolutions landing out of order. The test captures the DOM node
before and after, and was watched failing against a url-only key.
PERSISTENT_TAB_TYPES is hoisted to module scope and exported so it can be
asserted on -- it was a local const inside the component and therefore
untestable. web-endpoint is deliberately excluded: an idle tunnel re-binds a
fresh kernel-assigned port, so a restored tab could never hold a valid URL.
Two notes on verification. `tsc -p tsconfig.json` passes vacuously in this
repo -- tsconfig.json is a solution file with project references and does
nothing without -b -- so `npm run type-check` (tsc -b --force) is the real
check; it caught two insertions that had landed in the wrong function. And the
one full-suite failure seen along the way was vault-signer-core, which passes
in isolation and on re-run, is untouched by this branch, and is a flake under
parallel load.
Lint: 0 errors, 102 warnings, identical to the baseline on a clean tree.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Every route in routes.ts registers the full "/ssh/tunnel/..." path -- nginx proxies /ssh through with the path intact -- and the client resolves "/tunnel/web-endpoint/open" against a baseURL that already ends in /ssh. The unprefixed registration therefore 404'd every call. No handler unit test could catch this: they call handleWebEndpointOpen directly and never touch registration. It surfaced only on opening a real tunnel against a deployed build, which is why that step exists. Added a registration test that captures the paths passed to app.post, so the invariant is checked without needing a server. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Overview
Adds a per-host Web Endpoints feature: a host can declare the web UIs it
serves (scheme, port, path), openable from the sidebar either directly at
the host's address or through an SSH port-forward Termix establishes on
demand, rendered in the user's browser or an in-app iframe tab.
web:name, real bound-port reporting, and 10-minute idle closeenable_web_ui/web_ui_confighost columns threaded through the host read/write pathsChanges Made
WebEndpoint/WebUiConfigtypes, a backendnormalizer that never throws on malformed stored JSON, and an editor-side
validator kept honest by a drift test that runs both over the same samples.
Paths are control-character-checked by codepoint; bind hosts are validated to
a bare host literal (IPv4 / bracketed IPv6 / hostname).
tcpServer.address(), supports an idle timer that closes an unused webtunnel after ten minutes (via
cleanupTunnelResources, so the runtime entryis removed rather than a dead listener left registered), and reserves the
web:tunnel-name prefix with fail-closed parsing. Disconnect/cancelauthorization goes through a shared
authorizeTunnelAction.POST /ssh/tunnel/web-endpoint/openopens (or reuses) theforward for a numeric host id + endpoint id, probes the target, and returns
the local port. A target fingerprint (including SSH identity) reopens the
forward when the target changes.
can reach the forward at a different loopback spelling than the page host
(cookies ignore the port, so same-host would hand the tunnelled service
Termix's
jwt), and refuses a loopback-bound tunnel on a remote backend withan actionable message rather than framing a dead port. Desktop
(
allow-invalid-certificate-for-origin) grants per-origin, time-boxed certallowances for
ignoreCertendpoints, deliberately not wired into theprocess-wide TLS path.
editor), one sidebar "Web UI" entry that expands to a picker, and a lazy
WebEndpointTabthat re-resolves on reload and keys the iframe on ageneration counter so a same-port reopen still remounts.
Related Issues
Screenshots / Demos
Sidebar picker — one "Web UI" entry expands to the host's endpoints.
In-app tunnel tab — an endpoint framed at http://127.0.0.1:/… ; no cookie is attached to the framed request.
Browser refusal — a loopback-bound tunnel is refused in a browser deployment with an actionable message rather than a dead/leaking frame.
Checklist
Verification.
npm run type-check(tsc -b --force) clean.npx vitest run: 3080 passing, 1 skipped, 0 failing across 417 files — this branch carries an in-memorylocalStorageshim for the vitest environment (cd1d07a), which removes the 119-failure baseline previously seen ondev-2.8.0.npm run lint0 errors, 102 warnings (unchanged, no new warnings).prettier --checkclean.Manually verified against a freshly built Docker image on a new database (fresh SQLite round-trip, loopback vs all-interfaces bind confirmed in
/proc/net/tcp, LAN refusal from a separate container, browser end-to-end showingSec-Fetch-Dest: iframewith noCookieheader, real 10-minute idle close then rebind) and against the desktop app (dev-mode and the packagedfile://tar.gz build:isElectronpath live, session jar carries nojwt, SSH-tunnelled iframe reaches the target with no cookie, per-origin cert allowance proven the sole gate for a non-private origin).