@webda/debug 4.0.0-beta.4 → 4.0.0-beta.6

package/lib/debugservice.service.js

@@ -32,15 +32,15 @@ var __esDecorate = (this && this.__esDecorate) || function (ctor, descriptorIn,
     if (target) Object.defineProperty(target, contextIn.name, descriptor);
     done = true;
 };
-import { Service, ServiceParameters, useDynamicService, useCoreEvents, useRouter } from "@webda/core";
+import { Service, ServiceParameters, useDynamicService, useCoreEvents, useRouter, useApplication } from "@webda/core";
 import { Command } from "@webda/core";
 import { createServer } from "node:http";
-import { exec } from "node:child_process";
-import { readFileSync, existsSync } from "node:fs";
-import { platform } from "node:os";
+import { readFileSync, existsSync, statSync } from "node:fs";
 import { fileURLToPath } from "node:url";
+import { createRequire } from "node:module";
 import { dirname, join, extname } from "node:path";
 import { WebSocketServer, WebSocket } from "ws";
+import { BOOTSTRAP_CODE_TTL, DEBUG_API_VERSION, HOSTED_DASHBOARD_URL, LOCAL_PAGE_CSP, WS_PROTOCOL, allowedOrigins, buildDebugUrl, debugOrigins, extractBearerToken, extractWsToken, generateToken, isAllowedHost, isAllowedOrigin, openInBrowser, resolveTelemetry, safeEqual } from "./security.js";
 import { RequestLog } from "./requestlog.js";
 import { LogBuffer } from "./logbuffer.js";
 import { captureBody, normalizeHeaders } from "./bodycapture.js";
@@ -49,36 +49,61 @@ import { DebugTui } from "./tui/tui.js";
 import { CancelablePromise } from "@webda/utils";
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const WEBUI_DIR = join(__dirname, "..", "webui");
-/** Origins that are always allowed to access the debug API. */
-const ALLOWED_ORIGIN_EXACT = new Set([
-    "http://localhost:3000",
-    "http://127.0.0.1:3000",
-    "https://webda.io"
-]);
+export { isAllowedOrigin, allowedOrigins, DEBUG_API_VERSION } from "./security.js";
 /**
- * Determine whether the given Origin header value is allowed to access the debug API.
+ * Page served at `/` in hosted mode: no token, no bundle, just directions.
  *
- * Allowed origins:
- * - http://localhost:3000 (docs dev server)
- * - http://127.0.0.1:3000 (docs dev server, alternate address)
- * - https://webda.io (production docs)
- * - https://*.webda.io (any HTTPS subdomain of webda.io)
+ * @param hostedBase - the hosted dashboard URL
+ * @returns the HTML
+ */
+function hostedPlaceholderPage(hostedBase) {
+    const base = hostedBase.replace(/[<>&"]/g, "");
+    return `<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Webda debug server</title></head>
+<body style="font-family: system-ui, sans-serif; max-width: 40rem; margin: 4rem auto; line-height: 1.6">
+<h1>Webda debug server</h1>
+<p>This is the API of <code>webda debug --web</code>. The dashboard is hosted at
+<a href="${base}">${base}</a>: open the URL printed by the command, it carries your session.</p>
+<p>To serve the dashboard from here instead, restart with <code>webda debug --web --local</code>.</p>
+</body></html>
+`;
+}
+/**
+ * Version of this package, read once from its package.json.
+ * @returns the version string, or "unknown" when the file cannot be read
+ */
+function readDebugVersion() {
+    try {
+        return JSON.parse(readFileSync(join(__dirname, "..", "package.json"), "utf8")).version || "unknown";
+    }
+    catch {
+        return "unknown";
+    }
+}
+const DEBUG_VERSION = readDebugVersion();
+/**
+ * Version of the framework the application runs on.
  *
- * @param origin - The value of the HTTP `Origin` request header.
- * @returns `true` if the origin is allowed, `false` otherwise.
+ * Asks the application first, then reads the package.json of the `@webda/core`
+ * this package resolves (the application's one in a normal install).
+ * @returns the `@webda/core` version, or `undefined` when unavailable
  */
-export function isAllowedOrigin(origin) {
-    if (!origin)
-        return false;
-    if (ALLOWED_ORIGIN_EXACT.has(origin))
-        return true;
-    // Allow any https:// subdomain of webda.io
+function frameworkVersion() {
     try {
-        const u = new URL(origin);
-        return u.protocol === "https:" && u.hostname.endsWith(".webda.io");
+        const version = useApplication().getWebdaVersion();
+        if (version)
+            return version;
     }
     catch {
-        return false;
+        // application context unavailable, or getWebdaVersion failed
+    }
+    try {
+        const pkg = createRequire(import.meta.url).resolve("@webda/core/package.json");
+        return JSON.parse(readFileSync(pkg, "utf8")).version || undefined;
+    }
+    catch {
+        return undefined;
     }
 }
 /** Map file extensions to MIME types for static file serving. */
@@ -89,7 +114,12 @@ const MIME_TYPES = {
     ".json": "application/json; charset=utf-8",
     ".svg": "image/svg+xml",
     ".png": "image/png",
-    ".ico": "image/x-icon"
+    ".ico": "image/x-icon",
+    ".webp": "image/webp",
+    ".woff": "font/woff",
+    ".woff2": "font/woff2",
+    ".map": "application/json; charset=utf-8",
+    ".txt": "text/plain; charset=utf-8"
 };
 /**
  * Configuration parameters for the {@link DebugService}.
@@ -134,12 +164,60 @@ let DebugService = (() => {
                 this.requestLog = (__runInitializers(this, _instanceExtraInitializers), new RequestLog());
                 /** Ring buffer of application log entries */
                 this.logBuffer = new LogBuffer();
+                /** HTTP servers for the debug API (one per loopback address) */
+                this.servers = [];
                 /** Connected WebSocket clients */
                 this.clients = new Set();
                 /** Unsubscribe functions for core event listeners */
                 this.unsubscribers = [];
                 /** Timing map: requestId -> start timestamp */
                 this.timings = new Map();
+                /** Per-session token required on the API and the websocket */
+                this.token = generateToken();
+                /** Port the debug server actually listens on (resolved after listen) */
+                this.listeningPort = 0;
+                /** Whether the bundled dashboard is served (`--local`) */
+                this.localMode = false;
+                /** Origins allowed by CORS (computed at start from the environment) */
+                this.origins = allowedOrigins(process.env);
+            }
+            /**
+             * Port the debug server listens on (resolved after start).
+             * @returns the port
+             */
+            getPort() {
+                return this.listeningPort;
+            }
+            /**
+             * Loopback addresses the debug server is bound to.
+             * @returns the addresses, e.g. `["127.0.0.1", "::1"]`
+             */
+            getBoundAddresses() {
+                return this.servers
+                    .map(server => server.address()?.address)
+                    .filter((a) => !!a);
+            }
+            /**
+             * Issue a one-time bootstrap code for the local page (`--local`).
+             *
+             * The code is random, single-use and expires after {@link BOOTSTRAP_CODE_TTL};
+             * `POST /api/session` exchanges it for the session token.
+             * @param ttl - lifetime in milliseconds (tests use a negative value for an expired code)
+             * @returns the code
+             */
+            issueBootstrapCode(ttl = BOOTSTRAP_CODE_TTL) {
+                const code = generateToken();
+                this.bootstrap = { code, expires: Date.now() + ttl };
+                return code;
+            }
+            /**
+             * Session token required on every `/api/*` request and websocket connection.
+             *
+             * It is generated when the service is created and never logged.
+             * @returns the token
+             */
+            getToken() {
+                return this.token;
             }
             /**
              * Resolve the typed parameters and the capture knobs (with safe defaults
@@ -161,6 +239,9 @@ let DebugService = (() => {
              */
             resolve() {
                 super.resolve();
+                // The HTTP handler runs outside the application's async context, so the
+                // framework version is read here, where useApplication() is available.
+                this.frameworkVersion = frameworkVersion();
                 this.subscribeToEvents();
                 return this;
             }
@@ -303,8 +384,7 @@ let DebugService = (() => {
                     catch {
                         respBuf = undefined;
                     }
-                    const respContentType = (responseHeaders && (responseHeaders["Content-Type"] ?? responseHeaders["content-type"])) ||
-                        undefined;
+                    const respContentType = (responseHeaders && (responseHeaders["Content-Type"] ?? responseHeaders["content-type"])) || undefined;
                     if (respBuf !== undefined) {
                         details.responseBody = captureBody(respBuf, typeof respContentType === "string" ? respContentType : undefined, settings.bodyLimit, settings.binaryPreview);
                     }
@@ -327,7 +407,10 @@ let DebugService = (() => {
              *
              * @param port - Port for the debug dashboard API
              * @param servePort - Port for the application HTTP server
-             * @param web - Disable TUI and only serve the web dashboard
+             * @param web - Disable TUI and open the web dashboard instead
+             * @param local - Serve the bundled dashboard from the debug server instead of the hosted one
+             * @param open - Open the dashboard in the default browser (`--no-open` to disable)
+             * @param telemetry - Allow usage analytics on the hosted dashboard (`--no-telemetry` to disable)
              * @returns a promise settled once the service stops or the TUI quits
              */
             debug(
@@ -335,12 +418,18 @@ let DebugService = (() => {
             port = 18181, 
             /** @alias s @description Application server port */
             servePort = 18080, 
-            /** @description Disable TUI and only serve the web dashboard */
-            web) {
+            /** @description Disable TUI and open the web dashboard (hosted on webda.io) */
+            web, 
+            /** @description With --web: serve the bundled dashboard from the debug port instead of webda.io */
+            local, 
+            /** @description With --web: open the dashboard in the browser (--no-open to only print the URL) */
+            open = true, 
+            /** @description With --web: allow usage analytics on the hosted dashboard (--no-telemetry or WEBDA_TELEMETRY=0 to disable) */
+            telemetry = true) {
                 // Stays pending until the service stops or the TUI quits
                 return new CancelablePromise((resolve, reject) => {
                     this.running = resolve;
-                    this.startDebug(port, servePort, web).catch(reject);
+                    this.startDebug(port, servePort, web, local, open, telemetry).catch(reject);
                 }, async () => {
                     this.tui?.stop();
                 });
@@ -350,9 +439,12 @@ let DebugService = (() => {
              *
              * @param port - Port for the debug dashboard API
              * @param servePort - Port for the application HTTP server
-             * @param web - Disable TUI and only serve the web dashboard
+             * @param web - Disable TUI and open the web dashboard
+             * @param local - Serve the bundled dashboard instead of the hosted one
+             * @param open - Open the browser
+             * @param telemetry - Allow usage analytics on the hosted dashboard
              */
-            async startDebug(port, servePort, web) {
+            async startDebug(port, servePort, web, local, open = true, telemetry = true) {
                 // Start the main application server
                 const httpServer = useDynamicService("HttpServer");
                 if (httpServer?.start) {
@@ -360,23 +452,46 @@ let DebugService = (() => {
                     this.log("INFO", `Application server started on port ${servePort}`);
                 }
                 // Start the debug HTTP + WebSocket server
-                await this.startDebugServer(port);
-                this.log("INFO", `Debug dashboard API listening on port ${port}`);
+                await this.startDebugServer(port, { local: !!(web && local) });
+                this.log("INFO", `Debug dashboard API listening on 127.0.0.1:${this.listeningPort}`);
                 // Launch TUI by default, unless --web is passed
                 if (!web) {
-                    this.tui = new DebugTui(port);
+                    this.tui = new DebugTui(this.listeningPort, this.token);
                     // Quitting the TUI ends the command
                     this.tui.onStop = () => this.settle();
                     await this.tui.start();
+                    return;
                 }
-                else if (!process.env.WEBDA_DEBUG_NO_BROWSER) {
-                    // Headless callers (CI, Playwright's `webServer`, scripted smoke
-                    // tests) set WEBDA_DEBUG_NO_BROWSER=1 to suppress the auto-open —
-                    // they manage their own browser instance and don't want the local
-                    // Chrome to pop a stray tab on every server start.
-                    this.openBrowser(`http://localhost:${port}`);
+                const url = buildDebugUrl({
+                    port: this.listeningPort,
+                    token: this.token,
+                    local,
+                    code: local ? this.issueBootstrapCode() : undefined,
+                    telemetry: resolveTelemetry(telemetry, process.env),
+                    hostedBase: process.env.WEBDA_DEBUG_UI_URL
+                });
+                this.dashboardUrl = url;
+                this.printDashboardUrl(url);
+                // Headless callers (CI, Playwright's `webServer`, scripted smoke
+                // tests) set WEBDA_DEBUG_NO_BROWSER=1 to suppress the auto-open —
+                // they manage their own browser instance and don't want the local
+                // Chrome to pop a stray tab on every server start.
+                if (open && !process.env.WEBDA_DEBUG_NO_BROWSER) {
+                    this.openBrowser(url);
                 }
             }
+            /**
+             * Print the dashboard URL for the user.
+             *
+             * The hosted URL carries the session token in its fragment, so it is written
+             * straight to stdout rather than through the logger: log output is captured
+             * by the log buffer, broadcast to the dashboard and may be persisted by other
+             * loggers.
+             * @param url - the dashboard URL
+             */
+            printDashboardUrl(url) {
+                process.stdout.write(`\nWebda debug dashboard: ${url}\n\n`);
+            }
             /**
              * Settle the running debug command
              */
@@ -389,42 +504,144 @@ let DebugService = (() => {
              * @param url - URL to open
              */
             openBrowser(url) {
-                const cmd = platform() === "darwin" ? "open" : platform() === "win32" ? "start" : "xdg-open";
-                exec(`${cmd} ${url}`);
+                openInBrowser(url);
             }
             /**
              * Create and start the debug HTTP server with WebSocket support.
-             * @param port - Port to listen on
+             *
+             * One server per loopback address: `127.0.0.1` and `::1`, so that no other
+             * local process can squat the IPv6 side of `localhost`. A port already taken
+             * on either address is an error; an unavailable IPv6 stack is tolerated.
+             * The websocket upgrade is handled by hand so that the `Host`, `Origin` and
+             * token checks run before `ws` completes the handshake.
+             * @param port - Port to listen on (0 for a random one)
+             * @param options - local mode
              */
-            async startDebugServer(port) {
-                this.server = createServer((req, res) => this.handleRequest(req, res));
-                this.wss = new WebSocketServer({ server: this.server });
+            async startDebugServer(port, options = {}) {
+                this.localMode = !!options.local;
+                this.origins = allowedOrigins(process.env);
+                this.wss = new WebSocketServer({
+                    noServer: true,
+                    handleProtocols: protocols => (protocols.has(WS_PROTOCOL) ? WS_PROTOCOL : false)
+                });
                 this.wss.on("connection", (ws) => {
                     this.clients.add(ws);
                     ws.on("close", () => this.clients.delete(ws));
                     ws.on("error", () => this.clients.delete(ws));
                 });
-                await new Promise(resolve => {
-                    this.server.listen(port, () => resolve());
+                const v4 = await this.listen(port, "127.0.0.1");
+                this.server = v4;
+                this.listeningPort = v4.address().port;
+                try {
+                    await this.listen(this.listeningPort, "::1");
+                }
+                catch (err) {
+                    if (err?.code === "EADDRINUSE") {
+                        // Close without settling the command: the caller must see the failure
+                        await this.closeServers();
+                        throw new Error(`[::1]:${this.listeningPort} is already in use: refusing to start with half of localhost exposed`);
+                    }
+                    // EADDRNOTAVAIL / EAFNOSUPPORT: no IPv6 loopback on this host
+                    this.log("WARN", `IPv6 loopback unavailable (${err?.code || err}), listening on 127.0.0.1 only`);
+                }
+            }
+            /**
+             * Close every bound server.
+             */
+            async closeServers() {
+                for (const server of this.servers) {
+                    await new Promise(resolve => server.close(() => resolve()));
+                }
+                this.servers = [];
+                this.server = undefined;
+            }
+            /**
+             * Start one HTTP server on an address.
+             * @param port - the port
+             * @param address - the loopback address
+             * @returns the listening server
+             */
+            listen(port, address) {
+                return new Promise((resolve, reject) => {
+                    const server = createServer((req, res) => this.handleRequest(req, res));
+                    server.on("upgrade", (req, socket, head) => this.handleUpgrade(req, socket, head));
+                    server.once("error", reject);
+                    server.listen(port, address, () => {
+                        server.removeListener("error", reject);
+                        this.servers.push(server);
+                        resolve(server);
+                    });
+                });
+            }
+            /**
+             * Authenticate a websocket upgrade before handing it to `ws`.
+             * @param req - the upgrade request
+             * @param socket - the underlying socket
+             * @param head - the first packet of the upgraded stream
+             */
+            handleUpgrade(req, socket, head) {
+                const reject = (status, reason) => {
+                    socket.write(`HTTP/1.1 ${status} ${reason}\r\nConnection: close\r\nContent-Length: 0\r\n\r\n`);
+                    socket.destroy();
+                };
+                if (!isAllowedHost(req.headers.host, this.listeningPort)) {
+                    reject(403, "Forbidden");
+                    return;
+                }
+                // Browsers always send Origin on a websocket handshake: only the hosted
+                // dashboard and the debug origin itself may connect. No Origin = not a browser.
+                const origin = req.headers.origin;
+                if (origin && !this.isTrustedOrigin(origin)) {
+                    reject(403, "Forbidden");
+                    return;
+                }
+                if (!safeEqual(extractWsToken(req.headers["sec-websocket-protocol"]), this.token)) {
+                    reject(401, "Unauthorized");
+                    return;
+                }
+                this.wss.handleUpgrade(req, socket, head, ws => {
+                    this.wss.emit("connection", ws, req);
                 });
             }
+            /**
+             * Whether an Origin is the hosted dashboard, the dev server or the debug server itself.
+             * @param origin - the Origin header value
+             * @returns `true` when trusted
+             */
+            isTrustedOrigin(origin) {
+                return isAllowedOrigin(origin, this.origins) || debugOrigins(this.listeningPort).includes(origin);
+            }
             /**
              * Route incoming HTTP requests to introspection handlers.
              * @param req - Incoming HTTP request
              * @param res - Server response
              */
             handleRequest(req, res) {
+                // DNS rebinding: a page on evil.com whose DNS answer flips to 127.0.0.1
+                // still sends `Host: evil.com`; only loopback hosts are served.
+                if (!isAllowedHost(req.headers.host, this.listeningPort)) {
+                    this.sendJson(res, { error: "Forbidden" }, 403);
+                    return;
+                }
                 // CORS: echo the origin back only if it is on the allowlist.
                 // If there is no matching origin the browser will block cross-origin access,
                 // which is the desired behaviour. We also set Vary: Origin so that CDN /
                 // proxy caches do not serve a response with an allowed origin header to a
                 // different (disallowed) origin.
                 const origin = req.headers.origin;
-                if (isAllowedOrigin(origin)) {
+                const originAllowed = isAllowedOrigin(origin, this.origins);
+                // Vary on every response so that no cache serves one origin's answer to another
+                res.setHeader("Vary", "Origin");
+                if (originAllowed) {
                     res.setHeader("Access-Control-Allow-Origin", origin);
-                    res.setHeader("Vary", "Origin");
-                    res.setHeader("Access-Control-Allow-Methods", "GET, OPTIONS");
-                    res.setHeader("Access-Control-Allow-Headers", "Content-Type");
+                    res.setHeader("Access-Control-Allow-Methods", "GET, POST, OPTIONS");
+                    res.setHeader("Access-Control-Allow-Headers", "Authorization, Content-Type");
+                    res.setHeader("Access-Control-Max-Age", "600");
+                    // Private Network Access: the hosted dashboard (public) talks to
+                    // localhost (local); Chrome asks for this on the preflight.
+                    if (req.method === "OPTIONS" && req.headers["access-control-request-private-network"] === "true") {
+                        res.setHeader("Access-Control-Allow-Private-Network", "true");
+                    }
                 }
                 if (req.method === "OPTIONS") {
                     res.writeHead(204);
@@ -433,10 +650,29 @@ let DebugService = (() => {
                 }
                 const url = req.url || "/";
                 const pathname = url.split("?")[0];
+                if (!pathname.startsWith("/api/")) {
+                    this.serveStaticFile(pathname, req, res);
+                    return;
+                }
+                if (pathname === "/api/session") {
+                    this.handleSessionExchange(req, res);
+                    return;
+                }
+                // Every API response needs the session token; no data leaves without it.
+                if (!safeEqual(extractBearerToken(req.headers.authorization), this.token)) {
+                    res.setHeader("WWW-Authenticate", 'Bearer realm="webda-debug"');
+                    this.sendJson(res, { error: "Unauthorized" }, 401);
+                    return;
+                }
                 try {
                     // Route to handlers
                     if (pathname === "/api/info") {
-                        this.sendJson(res, getAppInfo());
+                        this.sendJson(res, {
+                            ...getAppInfo(),
+                            debugApiVersion: DEBUG_API_VERSION,
+                            debugVersion: DEBUG_VERSION,
+                            frameworkVersion: this.frameworkVersion
+                        });
                     }
                     else if (pathname === "/api/models") {
                         this.sendJson(res, getModels());
@@ -486,7 +722,7 @@ let DebugService = (() => {
                         this.sendJson(res, query ? this.logBuffer.search(query) : this.logBuffer.getEntries());
                     }
                     else {
-                        this.serveStaticFile(pathname, res);
+                        this.sendJson(res, { error: "Not found" }, 404);
                     }
                 }
                 catch (err) {
@@ -515,29 +751,136 @@ let DebugService = (() => {
                 }
             }
             /**
-             * Serve a static file from the webui directory.
-             * Falls back to index.html for SPA-style routing.
+             * `POST /api/session`: exchange the one-time bootstrap code for the session token (`--local` only).
+             *
+             * The code is printed in the local URL fragment; the page sends it once and
+             * keeps the token in memory. Accepted only from the debug origin itself (or
+             * without Origin, for non-browser clients); 404 in hosted mode so the route
+             * reveals nothing there. The code is consumed on a successful match only, and a
+             * reuse after it was spent is logged (the link was used by another client).
+             * @param req - the request
+             * @param res - the response
+             */
+            handleSessionExchange(req, res) {
+                if (!this.localMode) {
+                    this.sendJson(res, { error: "Not found" }, 404);
+                    return;
+                }
+                if (req.method !== "POST") {
+                    this.sendJson(res, { error: "Method not allowed" }, 405);
+                    return;
+                }
+                const origin = req.headers.origin;
+                if (origin && !debugOrigins(this.listeningPort).includes(origin)) {
+                    this.sendJson(res, { error: "Forbidden" }, 403);
+                    return;
+                }
+                let body = "";
+                req.on("data", chunk => {
+                    body += chunk;
+                    if (body.length > 4096)
+                        req.destroy();
+                });
+                req.on("end", () => {
+                    let code;
+                    try {
+                        code = JSON.parse(body || "null")?.code;
+                    }
+                    catch {
+                        code = undefined;
+                    }
+                    if (typeof code !== "string" || !code) {
+                        this.sendJson(res, { error: "Missing code" }, 400);
+                        return;
+                    }
+                    const pending = this.bootstrap;
+                    if (!pending) {
+                        // Either never issued, or already exchanged: a second correct-format attempt
+                        // after the exchange means another client used the link first
+                        this.log("WARN", "Debug session link refused: it was already used by another client or has expired");
+                        this.sendJson(res, { error: "Invalid or expired code" }, 403);
+                        return;
+                    }
+                    if (pending.expires < Date.now()) {
+                        this.bootstrap = undefined;
+                        this.sendJson(res, { error: "Invalid or expired code" }, 403);
+                        return;
+                    }
+                    if (!safeEqual(code, pending.code)) {
+                        // A wrong guess (256-bit code: brute force is infeasible) must not burn the real one
+                        this.sendJson(res, { error: "Invalid or expired code" }, 403);
+                        return;
+                    }
+                    // Single use: consumed only on a successful match
+                    this.bootstrap = undefined;
+                    this.sendJson(res, { token: this.token, debugApiVersion: DEBUG_API_VERSION });
+                });
+            }
+            /**
+             * Security headers of the pages and assets the debug server serves.
+             * @param res - the response
+             * @param html - whether the response is a page
+             */
+            pageHeaders(res, html) {
+                res.setHeader("Cache-Control", "no-store");
+                res.setHeader("X-Content-Type-Options", "nosniff");
+                if (html) {
+                    res.setHeader("Content-Security-Policy", LOCAL_PAGE_CSP);
+                    res.setHeader("X-Frame-Options", "DENY");
+                    res.setHeader("Referrer-Policy", "no-referrer");
+                }
+            }
+            /**
+             * Serve a static file from the webui directory (`--local`), or the hosted
+             * placeholder page.
+             *
+             * The page never carries the token: the local page obtains it through the
+             * one-time code exchange. Unknown paths fall back to index.html (SPA routing);
+             * directories are not found.
              * @param pathname - Request pathname
+             * @param req - Incoming request
              * @param res - Server response
              */
-            serveStaticFile(pathname, res) {
+            serveStaticFile(pathname, req, res) {
+                if (!this.localMode) {
+                    if (pathname === "/" || pathname === "/index.html") {
+                        this.pageHeaders(res, true);
+                        res.writeHead(200, { "Content-Type": MIME_TYPES[".html"] });
+                        res.end(hostedPlaceholderPage(process.env.WEBDA_DEBUG_UI_URL || HOSTED_DASHBOARD_URL));
+                        return;
+                    }
+                    this.sendJson(res, { error: "Not found" }, 404);
+                    return;
+                }
                 // Prevent directory traversal
                 const safePath = pathname.replace(/\.\./g, "").replace(/\/+/g, "/");
                 let filePath = join(WEBUI_DIR, safePath === "/" ? "index.html" : safePath);
-                // If the file doesn't exist, serve index.html (SPA fallback)
-                if (!existsSync(filePath)) {
+                // SPA fallback for unknown paths (not for existing directories such as /assets)
+                const isFile = (file) => {
+                    try {
+                        return statSync(file).isFile();
+                    }
+                    catch {
+                        return false;
+                    }
+                };
+                if (!isFile(filePath)) {
+                    if (existsSync(filePath) || safePath.startsWith("/assets")) {
+                        this.sendJson(res, { error: "Not found" }, 404);
+                        return;
+                    }
                     filePath = join(WEBUI_DIR, "index.html");
                 }
-                if (!existsSync(filePath)) {
+                if (!isFile(filePath)) {
                     this.sendJson(res, { error: "Not found" }, 404);
                     return;
                 }
                 try {
-                    const content = readFileSync(filePath);
                     const ext = extname(filePath);
                     const mime = MIME_TYPES[ext] || "application/octet-stream";
+                    this.pageHeaders(res, ext === ".html");
                     res.writeHead(200, { "Content-Type": mime });
-                    res.end(content);
+                    res.end(readFileSync(filePath));
                 }
                 catch {
                     this.sendJson(res, { error: "Internal server error" }, 500);
@@ -550,7 +893,7 @@ let DebugService = (() => {
              * @param statusCode - HTTP status code
              */
             sendJson(res, data, statusCode = 200) {
-                res.writeHead(statusCode, { "Content-Type": "application/json" });
+                res.writeHead(statusCode, { "Content-Type": "application/json", "Cache-Control": "no-store" });
                 res.end(JSON.stringify(data));
             }
             /**
@@ -585,10 +928,8 @@ let DebugService = (() => {
                     this.wss.close();
                     this.wss = undefined;
                 }
-                if (this.server) {
-                    await new Promise(resolve => this.server.close(() => resolve()));
-                    this.server = undefined;
-                }
+                await this.closeServers();
+                this.bootstrap = undefined;
                 this.timings.clear();
                 this.tui?.stop();
                 this.tui = undefined;
@@ -598,7 +939,10 @@ let DebugService = (() => {
         },
         (() => {
             const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(_classSuper[Symbol.metadata] ?? null) : void 0;
-            _debug_decorators = [Command("debug", { description: "Start dev server with debug dashboard", requires: ["router", "rest-domain", "http-server"] })];
+            _debug_decorators = [Command("debug", {
+                    description: "Start dev server with debug dashboard",
+                    requires: ["router", "rest-domain", "http-server"]
+                })];
             __esDecorate(_a, null, _debug_decorators, { kind: "method", name: "debug", static: false, private: false, access: { has: obj => "debug" in obj, get: obj => obj.debug }, metadata: _metadata }, null, _instanceExtraInitializers);
             if (_metadata) Object.defineProperty(_a, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });
         })(),