feat: move web endpoint into a first-party plugin

plugins/web-endpoint/backend/index.mjs

@@ -0,0 +1,75 @@
+/**
+ * Web Endpoint - first-party, in-process plugin.
+ *
+ * This plugin runs on the main thread because its one route is a real
+ * transport consumer: it polls the tunnel manager's live maps
+ * (activeTunnelRuntimes, connectionStatus, tunnelConnecting), needs the
+ * plaintext host credentials ctx.hosts deliberately withholds (PluginHostView
+ * is a 13-field allowlist excluding password, key and passphrase), and hands a
+ * live ssh2.Client to forwardOut to probe the target. None of that survives
+ * the structured-clone postMessage boundary a worker plugin talks over.
+ *
+ * Unlike every other dispatcher-backed plugin, this one does not register with
+ * a dispatcher in database.ts: its route is served by the tunnel service on
+ * port 30003, so the dispatcher lives at
+ * src/backend/hosts/tunnel/web-endpoint-dispatch.ts instead. Both that service
+ * and the plugin runtime load into the same backend process, so the
+ * dispatcher's module-level slot is shared between them. Keeping the URL
+ * (/ssh/tunnel/web-endpoint/open) byte-identical is also why no nginx change
+ * was needed -- the generic /ssh/tunnel/ location block already covers it.
+ *
+ * Three pieces stay in core rather than moving here:
+ *
+ *   - The tunnel manager itself (src/backend/hosts/tunnel/manager.ts). It
+ *     serves the whole server-tunnels feature, and the reserved "web:" name
+ *     prefix that exempts these tunnels from the retry machinery is part of
+ *     its own disconnect path.
+ *
+ *   - host-web-endpoints.ts (the webUiConfig normalizer). Despite its name it
+ *     has no router: it is imported by host.ts, host-bulk-routes.ts and
+ *     host-normalizers.ts to sanitize the column on every host save and list.
+ *     Disabling this plugin must not stop that validation, and core cannot
+ *     import plugin code in any case.
+ *
+ *   - The Electron half (electron/web-endpoint-window.cjs and the two
+ *     ipcMain handlers in main.cjs). BrowserWindow and session are
+ *     main-process-only, the renderer is what invokes those channels, and the
+ *     main process loads no plugin code at all today.
+ *
+ * The enableWebUi/webUiConfig columns stay on core's ssh_data table, declared
+ * here through contributes.hostCapability -- this plugin system has no
+ * owned-table migration mechanism of its own.
+ */
+
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+/**
+ * Loads a module by its path relative to this file's own directory.
+ *
+ * The plugin ships beside dist/backend, so in a built server the compiled .js
+ * for routes.js sits right next to this .mjs. Under vitest/dev nothing imports
+ * this plugin directly (the loader loads in-process plugins with a plain
+ * dynamic import, no tsx loader involved), so the only layout that needs to
+ * resolve here is the built one.
+ */
+async function loadRelative(relativePath) {
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  const target = path.join(here, `${relativePath}.js`);
+  return import(new URL(`file://${target.replace(/\\/g, "/")}`).href);
+}
+
+let routesModule = null;
+
+export async function activate(ctx) {
+  routesModule = await loadRelative("routes");
+  routesModule.startWebEndpointService();
+  ctx.log.info("Web Endpoint router registered at /ssh/tunnel/web-endpoint");
+}
+
+export async function deactivate() {
+  if (routesModule) {
+    routesModule.stopWebEndpointService();
+    routesModule = null;
+  }
+}

plugins/web-endpoint/backend/routes.ts

@@ -0,0 +1,323 @@
+import express from "express";
+import { Client } from "ssh2";
+import { AuthManager } from "../../../src/backend/utils/auth-manager.js";
+import { tunnelLogger } from "../../../src/backend/utils/logger.js";
+import { parseWebUiConfig } from "../../../src/backend/database/routes/host-web-endpoints.js";
+import {
+  activeTunnelRuntimes,
+  cleanupTunnelResources,
+  connectSSHTunnel,
+  connectionStatus,
+  tunnelConnecting,
+} from "../../../src/backend/hosts/tunnel/manager.js";
+import { forwardOut } from "../../../src/backend/hosts/tunnel/ssh-primitives.js";
+import { buildWebEndpointTunnelName } from "../../../src/backend/hosts/tunnel/utils.js";
+import {
+  registerWebEndpointRouter,
+  unregisterWebEndpointRouter,
+} from "../../../src/backend/hosts/tunnel/web-endpoint-dispatch.js";
+import type { TunnelConfig, WebEndpoint } from "../../../src/types/index.js";
+
+/** Matches the spec's ten minutes. */
+const WEB_ENDPOINT_IDLE_TIMEOUT_MS = 10 * 60 * 1000;
+
+/**
+ * Long enough for a slow SSH handshake, short enough that a wedged connection
+ * does not hold the HTTP request open indefinitely. One second past the
+ * manager's own connection timeout so the manager reports first.
+ */
+const TUNNEL_READY_TIMEOUT_MS = 61_000;
+const TUNNEL_READY_POLL_MS = 100;
+const TARGET_PROBE_TIMEOUT_MS = 10_000;
+
+/**
+ * What the live forward was built for. Compared on reuse so an endpoint edited
+ * under a live tunnel is reopened rather than silently forwarding to the old
+ * target.
+ *
+ * JSON rather than a joined string: no separator can be smuggled in by a field
+ * value, and the result stays readable in a log. The SSH identity is included
+ * because a host repointed at a different server must also invalidate the
+ * forward, not just a changed endpoint port.
+ */
+function targetFingerprint(
+  endpoint: Pick<
+    WebEndpoint,
+    "scheme" | "port" | "access" | "bindHost" | "localPort"
+  >,
+  host: { ip?: string; port?: number; username?: string },
+): string {
+  return JSON.stringify({
+    scheme: endpoint.scheme,
+    port: endpoint.port,
+    access: endpoint.access,
+    bindHost: endpoint.bindHost ?? null,
+    localPort: endpoint.localPort ?? null,
+    ip: host.ip ?? null,
+    sshPort: host.port ?? null,
+    username: host.username ?? null,
+  });
+}
+
+const openedTargets = new Map<string, string>();
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * connectSSHTunnel(config) returns Promise<void> and NEVER REJECTS: every
+ * failure path inside it reports over broadcastTunnelStatus and returns
+ * normally, and its own promise resolves right after conn.connect(), long
+ * before the SSH "ready" event that would populate activeTunnelRuntimes.
+ *
+ * So "awaited" is not "connected". This is what actually waits.
+ *
+ * Polling the maps the manager already exports, rather than adding a
+ * promise-returning variant to manager.ts: every existing caller of
+ * connectSSHTunnel is fire-and-forget by design (the connect route responds
+ * "Connection request received" immediately and reports asynchronously over
+ * the status broadcast), so changing that contract to serve one new caller is
+ * a far larger blast radius than polling here.
+ */
+async function waitForTunnelSettled(tunnelName: string): Promise<void> {
+  const deadline = Date.now() + TUNNEL_READY_TIMEOUT_MS;
+
+  while (Date.now() < deadline) {
+    if (activeTunnelRuntimes.has(tunnelName)) return;
+
+    const status = connectionStatus.get(tunnelName);
+    if (!tunnelConnecting.has(tunnelName) && status && !status.connected) {
+      throw new Error(status.reason || "The endpoint tunnel failed to connect");
+    }
+    await sleep(TUNNEL_READY_POLL_MS);
+  }
+
+  throw new Error("Timed out establishing the endpoint tunnel");
+}
+
+/**
+ * Opens one channel to the target and closes it immediately.
+ *
+ * Without this the route returns 200 the moment tcpServer.listen succeeds, and
+ * forwardOut is only attempted per inbound socket -- where a failure is
+ * swallowed by the socket's own error handling. The user then gets a blank
+ * frame and no message for the single likeliest error: nothing is actually
+ * listening on that port. Costs one round trip per open.
+ */
+async function probeEndpointTarget(
+  sourceClient: Client,
+  targetPort: number,
+  tunnelName: string,
+): Promise<void> {
+  const channel = await Promise.race([
+    forwardOut(sourceClient, "127.0.0.1", targetPort, tunnelName),
+    new Promise<never>((_resolve, reject) =>
+      setTimeout(
+        () => reject(new Error("Timed out reaching the endpoint port")),
+        TARGET_PROBE_TIMEOUT_MS,
+      ),
+    ),
+  ]);
+  try {
+    channel.end();
+  } catch {
+    // Already gone; the probe succeeded either way.
+  }
+}
+
+export async function handleWebEndpointOpen(
+  req: express.Request,
+  res: express.Response,
+): Promise<express.Response | void> {
+  const userId = (req as { userId?: string }).userId;
+  if (!userId) {
+    return res.status(401).json({ error: "Authentication required" });
+  }
+
+  const { hostId, endpointId } = req.body ?? {};
+  if (
+    !Number.isInteger(hostId) ||
+    hostId < 1 ||
+    typeof endpointId !== "string"
+  ) {
+    return res.status(400).json({ error: "Invalid web endpoint request" });
+  }
+
+  // Deliberately NOT gated to the desktop. The forward binds wherever this
+  // backend runs, exactly as the server tunnels feature does, and the
+  // endpoint's own bindHost decides whether that is reachable from the
+  // browser -- loopback for the desktop, an address the server answers on for
+  // a web deployment.
+
+  const { resolveHostById } =
+    await import("../../../src/backend/hosts/host-resolver.js");
+  const host = await resolveHostById(hostId, userId);
+  if (!host) {
+    return res.status(403).json({ error: "Host not found or access denied" });
+  }
+
+  // All three write paths null the config on disable, so a configured-but-
+  // disabled host is not normally reachable -- except a bulk update that sends
+  // only { webUiConfig } while the stored enable_web_ui is still 0. The UI
+  // reads as off everywhere in that state, so the endpoint merely being
+  // present in the config is not on its own a licence to open a tunnel.
+  if (!host.enableWebUi) {
+    return res
+      .status(400)
+      .json({ error: "Web endpoints are not enabled for this host" });
+  }
+
+  // Re-normalized rather than trusted: the stored value predates any later
+  // tightening of the rules, and this is the value a forward is built from.
+  const endpoint = parseWebUiConfig(host.webUiConfig).endpoints.find(
+    (candidate) => candidate.id === endpointId,
+  );
+  if (!endpoint) {
+    return res.status(400).json({ error: "Web endpoint not found" });
+  }
+  if (endpoint.access !== "tunnel") {
+    return res
+      .status(400)
+      .json({ error: "This endpoint does not use a tunnel" });
+  }
+
+  const tunnelName = buildWebEndpointTunnelName(hostId, endpointId);
+  const fingerprint = targetFingerprint(endpoint, host);
+  const existing = activeTunnelRuntimes.get(tunnelName);
+
+  if (existing) {
+    const recorded = openedTargets.get(tunnelName);
+    // The runtime is the source of truth and openedTargets is derived from it,
+    // so an ABSENT fingerprint means reuse, not staleness. A reserved-prefixed
+    // runtime can only have been created by this route.
+    if (recorded === undefined || recorded === fingerprint) {
+      openedTargets.set(tunnelName, fingerprint);
+      return res.status(200).json({ port: existing.bindPort });
+    }
+
+    tunnelLogger.info("Reopening web endpoint tunnel after config change", {
+      operation: "web_endpoint_reopen",
+      tunnelName,
+    });
+    // Forced, for the same reason handleDisconnect's reserved-name branch
+    // forces: cleanupTunnelResources no-ops while tunnelConnecting holds the
+    // name, and a web tunnel has no retry pass to self-heal a runtime left
+    // behind. An unforced call could leave a dead listener registered.
+    await cleanupTunnelResources(tunnelName, true);
+    openedTargets.delete(tunnelName);
+  }
+
+  const tunnelConfig: TunnelConfig = {
+    name: tunnelName,
+    scope: "s2s",
+    mode: "local",
+    tunnelType: "local",
+    // Loopback unless the endpoint asks otherwise. A non-loopback bind
+    // publishes the target's web UI to anyone who can reach the port, with no
+    // authentication in front of it -- the same trade the server tunnels
+    // feature exposes, and only ever an explicit per-endpoint choice. The
+    // value is validated to a bare host literal by normalizeBindHost.
+    bindHost: endpoint.bindHost || "127.0.0.1",
+    sourceHostId: host.id ?? hostId,
+    tunnelIndex: 0,
+    requestingUserId: userId,
+    hostName: host.name || `${host.username}@${host.ip}`,
+    sourceIP: host.ip,
+    sourceSSHPort: host.port,
+    sourceUsername: host.username,
+    sourcePassword: host.password,
+    sourceAuthMethod: host.authType,
+    sourceSSHKey: host.key,
+    sourceKeyPassword: host.keyPassword,
+    sourceKeyType: host.keyType,
+    sourceCredentialId: host.credentialId,
+    // connectSSHTunnel reads sourceUserId when building its client.
+    sourceUserId: host.userId,
+    endpointIP: host.ip,
+    endpointSSHPort: host.port,
+    endpointUsername: host.username,
+    // Load-bearing: connectSSHTunnel picks its strategy via
+    // shouldEstablishDirectTunnel -> isSingleHostTunnel, which returns true
+    // when endpointHost is "127.0.0.1". That is what selects
+    // establishDirectTunnel's local branch -- the bind-locally-and-forwardOut
+    // path this feature needs. Setting only targetHost would NOT select it.
+    endpointHost: "127.0.0.1",
+    endpointAuthMethod: host.authType,
+    endpointSSHKey: host.key,
+    endpointKeyPassword: host.keyPassword,
+    endpointKeyType: host.keyType,
+    endpointCredentialId: host.credentialId,
+    endpointUserId: host.userId,
+    // A fixed port when the endpoint names one, as the server tunnels
+    // feature's Source Port does -- a container can only publish ports it
+    // knows in advance. Otherwise 0 and the kernel picks; the manager reports
+    // back what it actually bound either way.
+    sourcePort: endpoint.localPort ?? 0,
+    endpointPort: endpoint.port,
+    // Documentation only: maxRetries 0 does NOT disable retries, because the
+    // manager reads `maxRetries || 3`. Retry is actually suppressed by the
+    // reserved-name early return in handleDisconnect.
+    maxRetries: 0,
+    retryInterval: 0,
+    autoStart: false,
+    isPinned: Boolean(host.pin),
+    idleTimeoutMs: WEB_ENDPOINT_IDLE_TIMEOUT_MS,
+    useSocks5: Boolean(host.useSocks5),
+    socks5Host: host.socks5Host,
+    socks5Port: host.socks5Port,
+    socks5Username: host.socks5Username,
+    socks5Password: host.socks5Password,
+    socks5ProxyChain: host.socks5ProxyChain,
+  } as TunnelConfig;
+
+  try {
+    await connectSSHTunnel(tunnelConfig);
+    await waitForTunnelSettled(tunnelName);
+
+    const runtime = activeTunnelRuntimes.get(tunnelName);
+    if (!runtime) {
+      throw new Error("The endpoint tunnel closed before it could be used");
+    }
+
+    await probeEndpointTarget(runtime.sourceClient, endpoint.port, tunnelName);
+
+    openedTargets.set(tunnelName, fingerprint);
+    return res.status(200).json({ port: runtime.bindPort });
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    tunnelLogger.error("Failed to open web endpoint tunnel", error, {
+      operation: "web_endpoint_open_failed",
+      tunnelName,
+    });
+    // Leave nothing half-built: a listener with no working forward behind it
+    // would be handed out on the next open as a live tunnel.
+    await cleanupTunnelResources(tunnelName, true).catch(() => undefined);
+    openedTargets.delete(tunnelName);
+    return res.status(502).json({ error: reason });
+  }
+}
+
+export const router = express.Router();
+
+let started = false;
+
+export function startWebEndpointService(): void {
+  if (!started) {
+    // Built on first start rather than at module scope so importing this
+    // module for a handler unit test does not construct the auth singleton.
+    const authenticateJWT = AuthManager.getInstance().createAuthMiddleware();
+    // Only "/open" here: the dispatcher this router is registered with is
+    // mounted at /ssh/tunnel/web-endpoint, so the full path stays
+    // /ssh/tunnel/web-endpoint/open exactly as before. The "/ssh" prefix is
+    // part of the path the tunnel service serves -- nginx proxies /ssh/tunnel/
+    // through with the path intact.
+    router.post("/open", authenticateJWT, handleWebEndpointOpen);
+    started = true;
+  }
+  registerWebEndpointRouter(router);
+}
+
+export function stopWebEndpointService(): void {
+  unregisterWebEndpointRouter();
+}