jishushell 0.4.24 → 0.5.15

package/dist/server.js

@@ -1,13 +1,15 @@
 import Fastify from "fastify";
 import fastifyStatic from "@fastify/static";
 import multipart from "@fastify/multipart";
-import { join, dirname } from "path";
+import { basename, dirname, join } from "path";
 import { existsSync, realpathSync } from "fs";
 import { fileURLToPath } from "url";
 import { request as httpRequest } from "http";
+import { request as httpsRequest } from "https";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
-import { ensureDirs, ensurePanelConfig, getPanelConfig, migrateCatalogSchemaIfNeeded, migrateHermesShimOutIfNeeded, migrateOpenclawCatalogIfNeeded, migrateOpenclawImageTagIfNeeded, } from "./config.js";
+import { ensureDirs, ensurePanelConfig, getPanelConfig, migrateCatalogSchemaIfNeeded, migrateHermesShimOutIfNeeded, migrateOpenclawCatalogIfNeeded, migrateOpenclawImageTagIfNeeded, getInternalMcpToken, } from "./config.js";
+import { timingSafeEqual } from "node:crypto";
 import { runStartupMigrations } from "./services/runtime/index.js";
 import { verifyToken } from "./auth.js";
 import { authRoutes } from "./routes/auth.js";
@@ -18,7 +20,15 @@ import { runtimeCatalogRoutes } from "./routes/runtime.js";
 import { appRoutes } from "./routes/apps.js";
 import { agentAppRoutes } from "./routes/agent-apps.js";
 import { llmRoutes } from "./routes/llm.js";
+import { filesRoutes } from "./routes/files.js";
+import { internalRoutes } from "./routes/internal.js";
+import { organizeRoutes } from "./routes/files-organize.js";
+import { fileMountsRoutes } from "./routes/file-mounts.js";
+import { webdavRoutes } from "./routes/webdav.js";
+import { externalMountsRoutes } from "./routes/external-mounts.js";
+import { FilesManager } from "./services/files-manager.js";
 import * as appManager from "./services/app/app-manager.js";
+import * as capabilityRegistry from "./services/capability-registry.js";
 import backupRoutes from "./routes/backup.js";
 import * as llmProxy from "./services/llm-proxy/index.js";
 import * as nomadManager from "./services/nomad-manager.js";
@@ -29,6 +39,107 @@ import { checkUpdate } from "./services/panel-manager.js";
 import { PROXY_IDENTITY_HEADERS } from "./constants.js";
 import { supportsGatewayWebsocket } from "./services/runtime/instance.js";
 const PUBLIC_PATHS = new Set(["/api/auth/status", "/api/auth/init", "/api/auth/login", "/api/setup/status", "/api/apps/validate-sudo-password"]);
+/** Slug charset for /apps/:slug — same as instance ids. */
+const SLUG_RE = /^[a-z0-9][a-z0-9-]{0,62}$/;
+/** Regex for top-level app WebSocket upgrades (AI-FS v1 W2.5 PR-8). */
+const APP_SLUG_WS_RE = /^\/apps\/([a-z0-9][a-z0-9-]{0,62})(\/.*)?$/;
+/**
+ * Resolve the upstream host/port for a top-level /apps/:slug request using
+ * the capability registry. Resolution order:
+ *   1. `<slug>-ui`   — canonical convention (e.g. filebrowser-ui)
+ *   2. `web-<slug>`  — web-* convention (e.g. web-filebrowser)
+ * Returns the first entry with status === "running", or null if none found.
+ */
+function resolveAppSlugUpstream(slug) {
+    const candidates = [`${slug}-ui`, `web-${slug}`];
+    for (const cap of candidates) {
+        const providers = capabilityRegistry.listProviders(cap);
+        const running = providers.find((p) => p.status === "running");
+        if (running) {
+            return { host: running.host, port: running.hostPort };
+        }
+    }
+    return null;
+}
+function hasValidPanelUpgradeToken(req) {
+    const authHeader = req.headers.authorization || "";
+    const match = authHeader.match(/^Bearer\s+(\S+)$/);
+    let token = match?.[1] || "";
+    if (!token) {
+        const cookie = req.headers.cookie || "";
+        const cookieMatch = cookie.match(/(?:^|;\s*)jishushell_session=([^;]*)/);
+        token = cookieMatch?.[1] || "";
+    }
+    return Boolean(token && token.length <= 4096 && verifyToken(token));
+}
+function isLoopbackSocket(socket) {
+    const remoteIp = socket.remoteAddress || "";
+    return remoteIp === "127.0.0.1" || remoteIp === "::1" || remoteIp === "::ffff:127.0.0.1";
+}
+function joinCapabilityUpstreamPath(basePath, suffix) {
+    const normalizedBase = typeof basePath === "string" && basePath.trim()
+        ? (basePath.startsWith("/") ? basePath : `/${basePath}`)
+        : "/";
+    const normalizedSuffix = suffix.replace(/^\/+/, "");
+    if (!normalizedSuffix)
+        return normalizedBase;
+    return `${normalizedBase.replace(/\/+$/, "")}/${normalizedSuffix}`;
+}
+export function stripPanelSessionCookie(value) {
+    if (value === undefined)
+        return undefined;
+    const cookie = Array.isArray(value) ? value.join("; ") : value;
+    const preserved = cookie
+        .split(";")
+        .map((part) => part.trim())
+        .filter((part) => part && !/^jishushell_session=/i.test(part));
+    return preserved.length ? preserved.join("; ") : undefined;
+}
+export function buildCapabilityWebSocketHeaders(headers, upstreamOrigin) {
+    const upstreamHeaders = {};
+    for (const [key, value] of Object.entries(headers)) {
+        if (value === undefined)
+            continue;
+        const lower = key.toLowerCase();
+        if (lower === "host" || PROXY_IDENTITY_HEADERS.has(lower))
+            continue;
+        if (lower === "authorization")
+            continue;
+        if (lower === "origin") {
+            upstreamHeaders[key] = upstreamOrigin;
+            continue;
+        }
+        if (lower === "cookie") {
+            const cookie = stripPanelSessionCookie(value);
+            if (cookie)
+                upstreamHeaders[key] = cookie;
+            continue;
+        }
+        upstreamHeaders[key] = value;
+    }
+    return upstreamHeaders;
+}
+function forwardWebSocketRejection(socket, res) {
+    const statusCode = res.statusCode || 502;
+    const statusMessage = res.statusMessage || "Bad Gateway";
+    try {
+        socket.write(`HTTP/1.1 ${statusCode} ${statusMessage}\r\nConnection: close\r\n\r\n`);
+    }
+    catch { }
+    res.resume();
+    socket.destroy();
+}
+export function selectRefererWebSocketCapability(capabilities, refererCapability, wsPath) {
+    const matches = capabilities.filter((capability) => {
+        if (capability.visibility === "internal")
+            return false;
+        const capabilityPath = (capability.path || "/").replace(/\/+$/, "") || "/";
+        return wsPath === capabilityPath || wsPath.startsWith(capabilityPath === "/" ? "/" : `${capabilityPath}/`);
+    });
+    return matches.find((capability) => capability.capability !== refererCapability)
+        ?? matches.find((capability) => capability.capability === refererCapability)
+        ?? null;
+}
 export async function createServer(options = {}) {
     const port = options.port ?? 8090;
     const host = options.host || "0.0.0.0";
@@ -42,7 +153,7 @@ export async function createServer(options = {}) {
         bodyLimit: 1048576,
     });
     // Allow empty JSON body for POST requests
-    app.addContentTypeParser("application/json", { parseAs: "string" }, (req, body, done) => {
+    app.addContentTypeParser("application/json", { parseAs: "string" }, (_req, body, done) => {
         if (!body || body.length === 0) {
             done(null, {});
         }
@@ -56,9 +167,49 @@ export async function createServer(options = {}) {
         }
     });
     // Parse text/plain and application/x-yaml as raw string (for app install endpoint)
-    app.addContentTypeParser(["text/plain", "application/x-yaml"], { parseAs: "string" }, (req, body, done) => {
+    app.addContentTypeParser(["text/plain", "application/x-yaml"], { parseAs: "string" }, (_req, body, done) => {
         done(null, body);
     });
+    // Fallback: pass any other content type through as the raw stream. Without
+    // this, /apps/:slug/* (W2.5 PR-8) would reject POST/PUT uploads with 415
+    // because Fastify's default behavior is to reject unparseable bodies.
+    // Specific routes that need typed bodies (octet-stream upload, etc.)
+    // register their own narrower parsers — those win over this catch-all.
+    app.addContentTypeParser("*", (_req, payload, done) => {
+        done(null, payload);
+    });
+    // Eager-init the internal MCP token so the file exists on disk before
+    // any agent container starts and tries to read it via env injection.
+    // Lazy-init would only fire on the first request that carries an
+    // X-Jishushell-Internal-Token header, which is too late for the
+    // adapter onBeforeStart that mounts the value into the container.
+    try {
+        getInternalMcpToken();
+    }
+    catch (e) {
+        console.warn(`[server] internal MCP token init skipped: ${e?.message ?? e}`);
+    }
+    // ── Auth middleware for /apps/* (AI-FS v1 W2.5 PR-8) ──────────────────
+    // Top-level reverse proxy for installed apps. Added in AI-FS v1 W2.5 PR-8.
+    // Pairs with `/api/instances/:id/provides/:cap/*` which is instance-scoped.
+    // This hook is scoped to /apps/* only so it does not double-fire with the
+    // existing /api/* hook below.
+    app.addHook("onRequest", async (request, reply) => {
+        const path = request.url.split("?")[0];
+        if (!path.startsWith("/apps/"))
+            return;
+        const authHeader = request.headers.authorization || "";
+        const match = authHeader.match(/^Bearer\s+(\S+)$/);
+        let token = match?.[1] || "";
+        if (!token) {
+            const cookie = request.headers.cookie || "";
+            const cookieMatch = cookie.match(/(?:^|;\s*)jishushell_session=([^;]*)/);
+            token = cookieMatch?.[1] || "";
+        }
+        if (!token || token.length > 4096 || !verifyToken(token)) {
+            return reply.status(401).send({ detail: "Unauthorized" });
+        }
+    });
     // Auth middleware
     app.addHook("onRequest", async (request, reply) => {
         const path = request.url.split("?")[0];
@@ -73,6 +224,35 @@ export async function createServer(options = {}) {
             }
             return;
         }
+        // Internal token path — used by:
+        //   (a) MCP shims spawned inside agent containers
+        //       (need BOTH X-Jishushell-Internal-Token + X-Jishushell-Instance)
+        //   (b) Panel app lifecycle scripts (post_start, etc.) calling back into
+        //       /api/internal/* on the same host
+        //       (need ONLY X-Jishushell-Internal-Token; no instance binding —
+        //        apps aren't instances)
+        // Combined with the standard JWT path below; we never require both.
+        const internalToken = request.headers["x-jishushell-internal-token"];
+        if (typeof internalToken === "string" && internalToken.length >= 32) {
+            const expected = getInternalMcpToken();
+            if (internalToken.length === expected.length &&
+                timingSafeEqual(Buffer.from(internalToken), Buffer.from(expected))) {
+                const instanceId = request.headers["x-jishushell-instance"];
+                if (typeof instanceId === "string" && instanceManager.getInstance(instanceId)) {
+                    request.internalCallerInstance = instanceId;
+                    return;
+                }
+                // Path (b): app-lifecycle / internal-only routes. Allowed without
+                // an instance header. The route is responsible for asserting the
+                // (request as any).internalCallerScope === "panel" tag before
+                // returning sensitive data.
+                if (path.startsWith("/api/internal/")) {
+                    request.internalCallerScope = "panel";
+                    return;
+                }
+            }
+            return reply.status(401).send({ detail: "Unauthorized" });
+        }
         // Check Authorization header first, then fall back to httpOnly cookie
         const authHeader = request.headers.authorization || "";
         const match = authHeader.match(/^Bearer\s+(\S+)$/);
@@ -120,6 +300,122 @@ export async function createServer(options = {}) {
     await app.register(agentAppRoutes);
     await app.register(llmRoutes);
     await app.register(backupRoutes);
+    await app.register(internalRoutes);
+    // Single FilesManager instance shared across /api/files, /webdav, and
+    // /api/files/external-mounts so a mutation on the mount list (PUT
+    // /external-mounts) is visible to every layer immediately.
+    const panelCfgForFiles = getPanelConfig();
+    const initialExternalMounts = Array.isArray(panelCfgForFiles.external_mounts)
+        ? panelCfgForFiles.external_mounts
+        : [];
+    const sharedFilesManager = new FilesManager({
+        externalMounts: initialExternalMounts,
+    });
+    await app.register(async (scope) => {
+        // Encapsulated registration so the route-scoped octet-stream parser
+        // does not leak to other routes (matches plan G6/D6 — Files is the
+        // only route that needs raw-stream uploads at W1).
+        await filesRoutes(scope, { filesManager: sharedFilesManager });
+        await organizeRoutes(scope, { filesManager: sharedFilesManager });
+        await fileMountsRoutes(scope);
+        await externalMountsRoutes(scope, { filesManager: sharedFilesManager });
+    });
+    // WebDAV runs in its own scope — it has independent auth (app password
+    // Basic Auth, NOT the panel JWT) and registers extra HTTP methods that
+    // we don't want leaking to other routes.
+    await app.register(async (scope) => {
+        await webdavRoutes(scope, { filesManager: sharedFilesManager });
+    });
+    // ── Top-level /apps/:slug/* reverse proxy (AI-FS v1 W2.5 PR-8) ───────────
+    // Reverse-proxies HTTP requests for installed apps to their capability
+    // upstream. Auth is handled by the onRequest hook above. The /apps/:slug
+    // prefix is NOT stripped — apps like Filebrowser are configured with
+    // --baseURL=/apps/filebrowser and expect the full path.
+    //
+    // Resolution order: `<slug>-ui` → `web-<slug>` (first running entry wins).
+    // 503 if no running provider found. 400 if slug is malformed.
+    //
+    // Registered BEFORE the SPA static fallback so explicit routes win.
+    const appsProxyHandler = async (req, reply) => {
+        const rawSlug = req.params.slug ?? "";
+        if (!SLUG_RE.test(rawSlug)) {
+            return reply.status(400).send({ detail: "Invalid app slug", slug: rawSlug });
+        }
+        const upstream = resolveAppSlugUpstream(rawSlug);
+        if (!upstream) {
+            return reply.status(503).send({ detail: "app not running", slug: rawSlug });
+        }
+        const { host: upstreamHost, port: upstreamPort } = upstream;
+        // Pass the full original path unchanged (including /apps/<slug> prefix).
+        const rawUrl = req.raw.url ?? "/";
+        const targetPath = rawUrl;
+        const hostHeader = `${upstreamHost}:${upstreamPort}`;
+        // Build forwarded headers: strip cookie and authorization to avoid
+        // leaking panel session credentials to third-party apps.
+        const forwardHeaders = {};
+        for (const [key, value] of Object.entries(req.headers)) {
+            if (value === undefined)
+                continue;
+            const lower = key.toLowerCase();
+            if (lower === "host")
+                continue;
+            if (lower === "cookie") {
+                const stripped = stripPanelSessionCookie(value);
+                if (stripped)
+                    forwardHeaders[key] = stripped;
+                continue;
+            }
+            if (lower === "authorization")
+                continue;
+            forwardHeaders[key] = value;
+        }
+        forwardHeaders["host"] = hostHeader;
+        // Hijack before writing to reply.raw so Fastify does not attempt its own
+        // lifecycle send after the handler returns.
+        reply.hijack();
+        await new Promise((resolve) => {
+            const proxyReq = httpRequest({
+                hostname: upstreamHost,
+                port: upstreamPort,
+                path: targetPath,
+                method: req.method,
+                headers: forwardHeaders,
+            }, (proxyRes) => {
+                // Stream the response back without buffering.
+                reply.raw.writeHead(proxyRes.statusCode ?? 502, proxyRes.headers);
+                proxyRes.pipe(reply.raw, { end: true });
+                proxyRes.on("end", resolve);
+                proxyRes.on("error", () => {
+                    try {
+                        reply.raw.end();
+                    }
+                    catch { }
+                    resolve();
+                });
+            });
+            proxyReq.on("error", (err) => {
+                console.error(`[apps-proxy] upstream error for slug=${rawSlug}:`, err.message);
+                if (!reply.raw.headersSent) {
+                    reply.raw.writeHead(502, { "content-type": "application/json" });
+                    reply.raw.end(JSON.stringify({ detail: "upstream error", slug: rawSlug }));
+                }
+                resolve();
+            });
+            // Forward request body if present (POST, PUT, PATCH, etc.)
+            if (req.rawBody) {
+                proxyReq.end(req.rawBody);
+            }
+            else if (req.raw.readable) {
+                req.raw.pipe(proxyReq, { end: true });
+                req.raw.on("end", () => { }); // ensure event fires
+            }
+            else {
+                proxyReq.end();
+            }
+        });
+    };
+    app.all("/apps/:slug", appsProxyHandler);
+    app.all("/apps/:slug/*", appsProxyHandler);
     // Serve frontend static files
     // Look for frontend dist in multiple locations
     const resolvedDir = existsSync(__dirname) ? realpathSync(__dirname) : __dirname;
@@ -142,6 +438,10 @@ export async function createServer(options = {}) {
                 root: assetsDir,
                 prefix: "/assets/",
                 decorateReply: false,
+                cacheControl: false,
+                setHeaders: (res) => {
+                    res.setHeader("Cache-Control", "public, max-age=31536000, immutable");
+                },
             });
         }
         // Serve other static files and SPA fallback
@@ -150,6 +450,16 @@ export async function createServer(options = {}) {
             prefix: "/",
             decorateReply: true,
             wildcard: false,
+            globIgnore: ["assets/**"],
+            cacheControl: false,
+            setHeaders: (res, filePath) => {
+                if (basename(filePath) === "index.html") {
+                    res.setHeader("Cache-Control", "no-store");
+                }
+                else {
+                    res.setHeader("Cache-Control", "public, max-age=0");
+                }
+            },
         });
         // SPA fallback: serve index.html for non-API, non-asset routes
         app.setNotFoundHandler(async (request, reply) => {
@@ -162,6 +472,10 @@ export async function createServer(options = {}) {
                     error: { message: "proxy route not found", type: "server_error" },
                 });
             }
+            if (path.startsWith("/assets/")) {
+                return reply.status(404).type("text/plain").send("Asset not found");
+            }
+            reply.header("Cache-Control", "no-store");
             return reply.sendFile("index.html");
         });
     }
@@ -242,20 +556,23 @@ export async function createServer(options = {}) {
                     // pinned digest tag rewrite can now succeed.
                     runStartupMigrations();
                 }
-                // Rebuild capability registry from running app instances
+                // Rebuild capability registry from app instances. PR 3 sub-step 3f
+                // of the app-interconnect design drops the legacy `portOverride`
+                // arg — each provide now resolves through `resolveProvideEndpoint`
+                // which reads the actual allocated port from runtime metadata, so
+                // multi-provide apps no longer collapse all entries onto the
+                // gateway port. For instances whose underlying job is currently
+                // not running, we still re-register the entries (so the
+                // Connections UI keeps them as greyed candidates) and immediately
+                // mark them stopped via `setProviderStatus` (§5.4 of the design).
                 try {
-                    for (const inst of instanceManager.listInstances()) {
-                        if (!inst.id || !inst.app_id)
-                            continue;
-                        const appData = appManager.getApp(inst.app_id);
-                        if (!appData || !appData.spec.provides?.length)
+                    for (const appData of appManager.listApps()) {
+                        if (!appData.spec.provides?.length)
                             continue;
-                        // Use the generic framework helper — it dispatches through
-                        // the runtime adapter and handles both OpenClaw (env var)
-                        // and adapter-based (runtime.ports[]) port discovery.
-                        const port = instanceManager.getGatewayPort(inst.id);
-                        if (port > 0) {
-                            appManager.registerCapabilities(inst.id, appData.spec, port);
+                        appManager.registerCapabilities(appData.manifest.id, appData.spec);
+                        const status = await nomadManager.getStatus(appData.manifest.id);
+                        if (status.status === "stopped") {
+                            capabilityRegistry.setProviderStatus(appData.manifest.id, "stopped");
                         }
                     }
                 }
@@ -296,11 +613,156 @@ export async function createServer(options = {}) {
     // request lifecycle. Fastify's internal headersTimeout (73s) kills hijacked
     // sockets, so we intercept upgrades before Fastify sees them.
     const GATEWAY_WS_RE = /^\/api\/instances\/([a-z0-9][a-z0-9-]{0,62})\/gateway(?:\/(.*))?$/;
+    const CAPABILITY_WS_RE = /^\/api\/instances\/([a-z0-9][a-z0-9-]{0,62})\/provides\/([^/?]+)(?:\/(.*))?$/;
+    // Match Referer pointing at a capability proxy page (used to resolve
+    // root-level WS upgrades initiated by embedded pages like Browserless debugger
+    // whose Web Workers create WS connections to the panel origin directly).
+    const CAPABILITY_REF_RE = /\/api\/instances\/([a-z0-9][a-z0-9-]{0,62})\/provides\/([^/?]+)/;
     app.server.on("upgrade", async (req, socket, head) => {
         const url = req.url || "";
         const path = url.split("?")[0];
-        const match = path.match(GATEWAY_WS_RE);
-        if (!match) {
+        const gatewayMatch = path.match(GATEWAY_WS_RE);
+        const capabilityMatch = path.match(CAPABILITY_WS_RE);
+        // ── /apps/:slug/* WebSocket upgrade (AI-FS v1 W2.5 PR-8) ──────────────
+        // Proxy WS upgrades for top-level installed apps. Same auth gate as HTTP.
+        const appSlugWsMatch = path.match(APP_SLUG_WS_RE);
+        if (appSlugWsMatch && !gatewayMatch && !capabilityMatch) {
+            const slug = appSlugWsMatch[1];
+            // Auth gate: same JWT cookie/bearer check as the HTTP handler above.
+            if (!hasValidPanelUpgradeToken(req)) {
+                socket.write("HTTP/1.1 401 Unauthorized\r\nConnection: close\r\n\r\n");
+                socket.destroy();
+                return;
+            }
+            const upstream = resolveAppSlugUpstream(slug);
+            if (!upstream) {
+                socket.write("HTTP/1.1 503 Service Unavailable\r\nConnection: close\r\n\r\n");
+                socket.destroy();
+                return;
+            }
+            const { host: upstreamHost, port: upstreamPort } = upstream;
+            const hostHeader = `${upstreamHost}:${upstreamPort}`;
+            const upstreamOrigin = `http://${hostHeader}`;
+            const qs = url.includes("?") ? url.slice(url.indexOf("?")) : "";
+            const targetPath = `${path}${qs}`;
+            // Build upstream WS headers: strip cookie (panel session) and authorization.
+            const upstreamHeaders = buildCapabilityWebSocketHeaders(req.headers, upstreamOrigin);
+            socket.setTimeout?.(0);
+            socket.setNoDelay?.(true);
+            socket.setKeepAlive?.(true, 30000);
+            let proxyReq;
+            try {
+                proxyReq = httpRequest({
+                    hostname: upstreamHost,
+                    port: upstreamPort,
+                    path: targetPath,
+                    method: "GET",
+                    timeout: 10_000,
+                    headers: {
+                        ...upstreamHeaders,
+                        host: hostHeader,
+                    },
+                });
+            }
+            catch {
+                try {
+                    socket.destroy();
+                }
+                catch { }
+                activeWsSockets.delete(socket);
+                return;
+            }
+            proxyReq.on("timeout", () => {
+                proxyReq.destroy();
+                socket.destroy();
+            });
+            proxyReq.on("upgrade", (_res, proxySocket, proxyHead) => {
+                proxySocket.setTimeout(0);
+                proxySocket.setNoDelay(true);
+                proxySocket.setKeepAlive(true, 30000);
+                proxySocket.pause();
+                let handshake = "HTTP/1.1 101 Switching Protocols\r\nUpgrade: websocket\r\nConnection: Upgrade\r\n";
+                for (const [k, v] of Object.entries(_res.headers)) {
+                    if (v !== undefined && k.toLowerCase().startsWith("sec-websocket-")) {
+                        handshake += `${k}: ${v}\r\n`;
+                    }
+                }
+                handshake += "\r\n";
+                socket.write(handshake);
+                if (head.length > 0)
+                    proxySocket.write(head);
+                if (proxyHead.length > 0)
+                    socket.write(proxyHead);
+                proxySocket.pipe(socket);
+                socket.pipe(proxySocket);
+                proxySocket.resume();
+                activeWsSockets.add(socket);
+                activeWsSockets.add(proxySocket);
+                const release = (s) => { activeWsSockets.delete(s); };
+                const fail = () => {
+                    try {
+                        proxySocket.destroy();
+                    }
+                    catch { }
+                    try {
+                        socket.destroy();
+                    }
+                    catch { }
+                    release(socket);
+                    release(proxySocket);
+                };
+                proxySocket.on("close", () => {
+                    release(proxySocket);
+                    try {
+                        if (!socket.destroyed && !socket.writableEnded)
+                            socket.end();
+                    }
+                    catch { }
+                });
+                socket.on("close", () => {
+                    release(socket);
+                    try {
+                        if (!proxySocket.destroyed && !proxySocket.writableEnded)
+                            proxySocket.end();
+                    }
+                    catch { }
+                });
+                proxySocket.on("error", fail);
+                socket.on("error", fail);
+            });
+            proxyReq.on("response", (res) => {
+                forwardWebSocketRejection(socket, res);
+                activeWsSockets.delete(socket);
+            });
+            proxyReq.on("error", () => {
+                try {
+                    socket.write("HTTP/1.1 502 Bad Gateway\r\nConnection: close\r\n\r\n");
+                }
+                catch { }
+                socket.destroy();
+                activeWsSockets.delete(socket);
+            });
+            proxyReq.end();
+            return;
+        }
+        // ── end /apps/:slug/* WS upgrade ───────────────────────────────────────
+        // When an embedded page (e.g. Browserless debugger's puppeteer Worker)
+        // opens a WS to the panel origin at a non-API path (e.g. /?launch=...),
+        // resolve the target instance via the Referer header pointing at the
+        // capability proxy page that served the embedded UI.
+        let refererCapabilityMatch = null;
+        if (!gatewayMatch && !capabilityMatch) {
+            const referer = req.headers.referer || "";
+            try {
+                const refUrl = new URL(referer, "http://localhost");
+                const m = refUrl.pathname.match(CAPABILITY_REF_RE);
+                if (m) {
+                    refererCapabilityMatch = { instanceId: m[1], capability: decodeURIComponent(m[2]) };
+                }
+            }
+            catch { /* ignore malformed referer */ }
+        }
+        if (!gatewayMatch && !capabilityMatch && !refererCapabilityMatch) {
             // Not a gateway WebSocket — let it drop (Fastify doesn't handle WS natively)
             socket.destroy();
             return;
@@ -308,8 +770,7 @@ export async function createServer(options = {}) {
         // Defense-in-depth: validate Origin header for WebSocket upgrades.
         // Require Origin for non-loopback clients; gateway has its own token auth as primary.
         const origin = req.headers.origin || "";
-        const remoteIp = socket.remoteAddress || "";
-        const isLoopback = remoteIp === "127.0.0.1" || remoteIp === "::1" || remoteIp === "::ffff:127.0.0.1";
+        const isLoopback = isLoopbackSocket(socket);
         if (!origin && !isLoopback) {
             socket.write("HTTP/1.1 403 Forbidden\r\n\r\n");
             socket.destroy();
@@ -331,6 +792,276 @@ export async function createServer(options = {}) {
                 return;
             }
         }
+        if ((capabilityMatch || refererCapabilityMatch) && !hasValidPanelUpgradeToken(req)) {
+            socket.write("HTTP/1.1 401 Unauthorized\r\nConnection: close\r\n\r\n");
+            socket.destroy();
+            return;
+        }
+        // Referer-based WS proxy: embedded pages (like Browserless debugger's Web
+        // Worker) open WS connections to the panel origin (e.g. ws://panel:8090/?launch=...).
+        // We resolve the correct upstream by finding a capability on the same
+        // instance that serves the request path (e.g. path "/" with http protocol).
+        if (refererCapabilityMatch) {
+            const id = refererCapabilityMatch.instanceId;
+            const appData = instanceManager.getApp(id);
+            if (!appData) {
+                socket.destroy();
+                return;
+            }
+            const capabilities = instanceManager.getProvidedCapabilitiesForApp(id);
+            // Find a capability whose path prefix matches the WS request path.
+            // Prefer capabilities with path "/" (root API) that aren't the debugger UI itself.
+            const wsPath = path || "/";
+            const capability = selectRefererWebSocketCapability(capabilities, refererCapabilityMatch.capability, wsPath);
+            if (!capability || typeof capability.port !== "number" || capability.port < 1) {
+                try {
+                    socket.write("HTTP/1.1 404 Not Found\r\nConnection: close\r\n\r\n");
+                }
+                catch { }
+                socket.destroy();
+                return;
+            }
+            const protocol = String(capability.protocol || "http").toLowerCase();
+            const upstreamRequest = protocol === "https" || protocol === "wss" ? httpsRequest : httpRequest;
+            const targetHost = await instanceManager.getHostForAppPort(id, capability.port);
+            const hostHeader = `${instanceManager.urlHost(targetHost)}:${capability.port}`;
+            const upstreamOrigin = `${protocol === "https" || protocol === "wss" ? "https" : "http"}://${hostHeader}`;
+            const qs = url.includes("?") ? url.slice(url.indexOf("?")) : "";
+            const targetPath = `${joinCapabilityUpstreamPath(capability.path, path.replace(/^\/+/, ""))}${qs}`;
+            const upstreamHeaders = buildCapabilityWebSocketHeaders(req.headers, upstreamOrigin);
+            socket.setTimeout?.(0);
+            socket.setNoDelay?.(true);
+            socket.setKeepAlive?.(true, 30000);
+            let proxyReq;
+            try {
+                proxyReq = upstreamRequest({
+                    hostname: targetHost,
+                    port: capability.port,
+                    path: targetPath,
+                    method: "GET",
+                    timeout: 10_000,
+                    headers: {
+                        ...upstreamHeaders,
+                        host: hostHeader,
+                    },
+                });
+            }
+            catch {
+                try {
+                    socket.destroy();
+                }
+                catch { }
+                activeWsSockets.delete(socket);
+                return;
+            }
+            proxyReq.on("timeout", () => {
+                proxyReq.destroy();
+                socket.destroy();
+            });
+            proxyReq.on("upgrade", (_res, proxySocket, proxyHead) => {
+                proxySocket.setTimeout(0);
+                proxySocket.setNoDelay(true);
+                proxySocket.setKeepAlive(true, 30000);
+                proxySocket.pause();
+                let handshake = "HTTP/1.1 101 Switching Protocols\r\nUpgrade: websocket\r\nConnection: Upgrade\r\n";
+                for (const [k, v] of Object.entries(_res.headers)) {
+                    if (v !== undefined && k.toLowerCase().startsWith("sec-websocket-")) {
+                        handshake += `${k}: ${v}\r\n`;
+                    }
+                }
+                handshake += "\r\n";
+                socket.write(handshake);
+                if (head.length > 0)
+                    proxySocket.write(head);
+                if (proxyHead.length > 0)
+                    socket.write(proxyHead);
+                proxySocket.pipe(socket);
+                socket.pipe(proxySocket);
+                proxySocket.resume();
+                activeWsSockets.add(socket);
+                activeWsSockets.add(proxySocket);
+                const release = (s) => { activeWsSockets.delete(s); };
+                const fail = () => {
+                    try {
+                        proxySocket.destroy();
+                    }
+                    catch { }
+                    try {
+                        socket.destroy();
+                    }
+                    catch { }
+                    release(socket);
+                    release(proxySocket);
+                };
+                proxySocket.on("close", () => {
+                    release(proxySocket);
+                    try {
+                        if (!socket.destroyed && !socket.writableEnded)
+                            socket.end();
+                    }
+                    catch { }
+                });
+                socket.on("close", () => {
+                    release(socket);
+                    try {
+                        if (!proxySocket.destroyed && !proxySocket.writableEnded)
+                            proxySocket.end();
+                    }
+                    catch { }
+                });
+                proxySocket.on("error", fail);
+                socket.on("error", fail);
+            });
+            proxyReq.on("response", (res) => {
+                forwardWebSocketRejection(socket, res);
+                activeWsSockets.delete(socket);
+            });
+            proxyReq.on("error", () => {
+                try {
+                    socket.write("HTTP/1.1 502 Bad Gateway\r\nConnection: close\r\n\r\n");
+                }
+                catch { }
+                socket.destroy();
+                activeWsSockets.delete(socket);
+            });
+            proxyReq.end();
+            return;
+        }
+        if (capabilityMatch) {
+            const id = capabilityMatch[1];
+            const capabilityName = decodeURIComponent(capabilityMatch[2] || "");
+            const appData = instanceManager.getApp(id);
+            if (!appData) {
+                socket.destroy();
+                return;
+            }
+            const capability = instanceManager.getProvidedCapabilitiesForApp(id).find((entry) => entry.capability === capabilityName);
+            if (!capability || capability.visibility === "internal") {
+                try {
+                    socket.write("HTTP/1.1 404 Not Found\r\nConnection: close\r\n\r\n");
+                }
+                catch { }
+                socket.destroy();
+                return;
+            }
+            if (typeof capability.port !== "number" || capability.port < 1) {
+                try {
+                    socket.write("HTTP/1.1 500 Internal Server Error\r\nConnection: close\r\n\r\n");
+                }
+                catch { }
+                socket.destroy();
+                return;
+            }
+            const protocol = String(capability.protocol || "http").toLowerCase();
+            const upstreamRequest = protocol === "https" || protocol === "wss" ? httpsRequest : httpRequest;
+            const targetHost = await instanceManager.getHostForAppPort(id, capability.port);
+            const hostHeader = `${instanceManager.urlHost(targetHost)}:${capability.port}`;
+            const upstreamOrigin = `${protocol === "https" || protocol === "wss" ? "https" : "http"}://${hostHeader}`;
+            const suffix = capabilityMatch[3] || "";
+            const qs = url.includes("?") ? url.slice(url.indexOf("?")) : "";
+            const targetPath = `${joinCapabilityUpstreamPath(capability.path, suffix)}${qs}`;
+            const upstreamHeaders = buildCapabilityWebSocketHeaders(req.headers, upstreamOrigin);
+            socket.setTimeout?.(0);
+            socket.setNoDelay?.(true);
+            socket.setKeepAlive?.(true, 30000);
+            let proxyReq;
+            try {
+                proxyReq = upstreamRequest({
+                    hostname: targetHost,
+                    port: capability.port,
+                    path: targetPath,
+                    method: "GET",
+                    timeout: 10_000,
+                    headers: {
+                        ...upstreamHeaders,
+                        host: hostHeader,
+                    },
+                });
+            }
+            catch {
+                try {
+                    socket.destroy();
+                }
+                catch { }
+                activeWsSockets.delete(socket);
+                return;
+            }
+            proxyReq.on("timeout", () => {
+                proxyReq.destroy();
+                socket.destroy();
+            });
+            proxyReq.on("upgrade", (_res, proxySocket, proxyHead) => {
+                proxySocket.setTimeout(0);
+                proxySocket.setNoDelay(true);
+                proxySocket.setKeepAlive(true, 30000);
+                proxySocket.pause();
+                let handshake = "HTTP/1.1 101 Switching Protocols\r\nUpgrade: websocket\r\nConnection: Upgrade\r\n";
+                for (const [k, v] of Object.entries(_res.headers)) {
+                    if (v !== undefined && k.toLowerCase().startsWith("sec-websocket-")) {
+                        handshake += `${k}: ${v}\r\n`;
+                    }
+                }
+                handshake += "\r\n";
+                socket.write(handshake);
+                if (head.length > 0)
+                    proxySocket.write(head);
+                if (proxyHead.length > 0)
+                    socket.write(proxyHead);
+                proxySocket.pipe(socket);
+                socket.pipe(proxySocket);
+                proxySocket.resume();
+                activeWsSockets.add(socket);
+                activeWsSockets.add(proxySocket);
+                const release = (s) => {
+                    activeWsSockets.delete(s);
+                };
+                const fail = () => {
+                    try {
+                        proxySocket.destroy();
+                    }
+                    catch { }
+                    try {
+                        socket.destroy();
+                    }
+                    catch { }
+                    release(socket);
+                    release(proxySocket);
+                };
+                proxySocket.on("close", () => {
+                    release(proxySocket);
+                    try {
+                        if (!socket.destroyed && !socket.writableEnded)
+                            socket.end();
+                    }
+                    catch { }
+                });
+                socket.on("close", () => {
+                    release(socket);
+                    try {
+                        if (!proxySocket.destroyed && !proxySocket.writableEnded)
+                            proxySocket.end();
+                    }
+                    catch { }
+                });
+                proxySocket.on("error", fail);
+                socket.on("error", fail);
+            });
+            proxyReq.on("response", (res) => {
+                forwardWebSocketRejection(socket, res);
+                activeWsSockets.delete(socket);
+            });
+            proxyReq.on("error", () => {
+                try {
+                    socket.write("HTTP/1.1 502 Bad Gateway\r\nConnection: close\r\n\r\n");
+                }
+                catch { }
+                socket.destroy();
+                activeWsSockets.delete(socket);
+            });
+            proxyReq.end();
+            return;
+        }
+        const match = gatewayMatch;
         const id = match[1];
         const inst = instanceManager.getInstance(id);
         if (!inst) {