feat(desktop): open HTTP assets from client protocol URLs

Route jms2 HTTP/HTTPS payloads into the built-in web proxy, keep Core web_proxy as a client method on web, and add a download-client shortcut on the connection setup pane.

Author: ZhaoJiSen

electron/src/apps/local-app-launcher.ts

@@ -1,19 +1,9 @@
 import { spawn } from "node:child_process";
 import { mkdir, stat, writeFile } from "node:fs/promises";
 import path from "node:path";
+import { decodeClientProtocolPayload as decodePayload } from "../shared/client-protocol";
 import { electronLog } from "../shared/debug-log";
 
-function decodePayload(raw) {
-  const value = String(raw || "");
-  const encoded = value.startsWith("jms2://") ? value.slice(7) : "";
-  if (!encoded) throw new Error("invalid local client URL scheme");
-  try {
-    return JSON.parse(Buffer.from(encoded, "base64").toString("utf8"));
-  } catch (error) {
-    throw new Error(`decode local client payload failed: ${error instanceof Error ? error.message : error}`);
-  }
-}
-
 function sanitizedName(raw) {
   let decoded = String(raw || "");
   try {

electron/src/desktop/main.ts

@@ -34,7 +34,12 @@ import { FfmpegPluginManager } from "../replay/ffmpeg-plugin";
 import { OfflineRecordingStore } from "../replay/offline-recordings";
 import { ReplayTranscoder } from "../replay/transcoder";
 import { readableToWebBody } from "../shared/bytes";
-import { findClientProtocolUrl, normalizeClientProtocolUrl } from "../shared/client-protocol";
+import {
+  decodeClientProtocolPayload,
+  findClientProtocolUrl,
+  isWebAssetClientProtocolPayload,
+  normalizeClientProtocolUrl
+} from "../shared/client-protocol";
 import {
   activateDebugLogService,
   DebugLogService,
@@ -1291,6 +1296,7 @@ async function handleInvoke(event, request) {
     return applicationConfig.updateCustomTerminal({ ...args, path: resolveExecutablePath(args.path) });
   }
   if (command === "pull_up") return withIpcErrorLog("pull_up", () => localApplicationLauncher.launch(args.url));
+  if (command === "take_web_protocol_payloads") return takePendingWebProtocolPayloads();
   if (command === "list_system_fonts") return listSystemFonts();
   if (command === "cancel_transcode") return replayTranscoder.cancelCurrent(labelForWindow(win));
   if (command === "transcode_replays") {
@@ -1409,8 +1415,21 @@ interface PendingProtocolUrl {
 }
 
 const pendingProtocolUrls: PendingProtocolUrl[] = [];
+const pendingWebProtocolPayloads: Array<{
+  url: string;
+  payload: ReturnType<typeof decodeClientProtocolPayload>;
+}> = [];
 let startupFinished = false;
 
+function queueWebProtocolPayload(url: string, payload: ReturnType<typeof decodeClientProtocolPayload>) {
+  if (pendingWebProtocolPayloads.some((pending) => pending.url === url)) return;
+  pendingWebProtocolPayloads.push({ url, payload });
+}
+
+function takePendingWebProtocolPayloads() {
+  return pendingWebProtocolPayloads.splice(0).map((pending) => pending.payload);
+}
+
 function describeProtocolUrl(rawUrl) {
   const value = String(rawUrl || "");
   if (isOAuthCallbackUrl(value)) return "auth-callback";
@@ -1420,6 +1439,12 @@ function describeProtocolUrl(rawUrl) {
 
 async function processIncomingProtocolUrl(value: string) {
   if (authService.handleCallback(value) || authService.isOAuthCallbackUrl(value)) return false;
+  const payload = decodeClientProtocolPayload(value);
+  if (isWebAssetClientProtocolPayload(payload)) {
+    queueWebProtocolPayload(value, payload);
+    if (startupFinished) sendMainWindowEvent("web-protocol-url", null);
+    return false;
+  }
   await localApplicationLauncher.launch(value);
   return true;
 }

electron/src/shared/client-protocol.ts

@@ -22,6 +22,36 @@ export function normalizeClientProtocolUrl(raw: unknown): string | undefined {
   if (/^jms2:\/\//i.test(value)) return `${CLIENT_PROTOCOL}:${value.slice(value.indexOf(":") + 1)}`;
 }
 
+export interface ClientProtocolPayload {
+  protocol?: string;
+  asset?: { id?: unknown; [key: string]: unknown };
+  token?: { id?: unknown; protocol?: string; [key: string]: unknown };
+  file?: { content?: unknown; [key: string]: unknown };
+  endpoint?: { host?: unknown; port?: unknown; [key: string]: unknown };
+  [key: string]: unknown;
+}
+
+export function decodeClientProtocolPayload(raw: unknown): ClientProtocolPayload {
+  const value = normalizeClientProtocolUrl(raw);
+  const encoded = value?.startsWith(`${CLIENT_PROTOCOL}://`) ? value.slice(`${CLIENT_PROTOCOL}://`.length) : "";
+  if (!encoded) throw new Error("invalid local client URL scheme");
+  try {
+    const payload: unknown = JSON.parse(Buffer.from(encoded, "base64").toString("utf8"));
+    if (!payload || Array.isArray(payload) || typeof payload !== "object") throw new Error("payload must be an object");
+    return payload as ClientProtocolPayload;
+  } catch (error) {
+    throw new Error(`decode local client payload failed: ${error instanceof Error ? error.message : error}`);
+  }
+}
+
+export function isWebAssetClientProtocolPayload(payload: ClientProtocolPayload) {
+  return (
+    ["http", "https"].includes(String(payload.protocol || "").toLowerCase()) &&
+    typeof payload.asset?.id === "string" &&
+    Boolean(payload.asset.id.trim())
+  );
+}
+
 export function findClientProtocolUrl(argv: string[], additionalData?: unknown): string | undefined {
   if (additionalData && typeof additionalData === "object" && "protocolUrl" in additionalData) {
     const forwarded = normalizeClientProtocolUrl(additionalData.protocolUrl);

electron/tests/client-protocol.test.ts

@@ -9,11 +9,46 @@ import test from "node:test";
 import ts from "typescript";
 import {
   CLIENT_AUTH_CALLBACK,
+  decodeClientProtocolPayload,
   findClientProtocolUrl,
+  isWebAssetClientProtocolPayload,
   normalizeClientProtocolUrl,
   registerClientProtocol
 } from "../src/shared/client-protocol.ts";
 
+function loadTestDependency(require: NodeJS.Require, name: string) {
+  switch (name) {
+    case "../../../ui/utils/apiError":
+      return require("../../../ui/utils/apiError");
+    case "../package.json":
+      return require("../package.json");
+    case "../shared/client-protocol":
+      return require("../shared/client-protocol");
+    case "../shared/debug-log":
+      return require("../shared/debug-log");
+    case "../shared/url":
+      return require("../shared/url");
+    case "./oauth-callback":
+      return require("./oauth-callback");
+    case "./shared/product-name":
+      return require("./shared/product-name");
+    case "node:child_process":
+      return require("node:child_process");
+    case "node:crypto":
+      return require("node:crypto");
+    case "node:events":
+      return require("node:events");
+    case "node:fs/promises":
+      return require("node:fs/promises");
+    case "node:http":
+      return require("node:http");
+    case "node:path":
+      return require("node:path");
+    default:
+      throw new Error(`Unexpected test dependency: ${name}`);
+  }
+}
+
 // Execute the real entry/service code with Electron replaced; no desktop or OS
 // registration is touched by these Windows lifecycle checks on other platforms.
 function loadWithElectronMocks(relativePath: string, replacements: Record<string, unknown>, runtime = process) {
@@ -25,7 +60,8 @@ function loadWithElectronMocks(relativePath: string, replacements: Record<string
   const exports: Record<string, any> = {};
   runInNewContext(output.outputText, {
     exports,
-    require: (name: string) => (Object.hasOwn(replacements, name) ? replacements[name] : require(name)),
+    require: (name: string) =>
+      Object.hasOwn(replacements, name) ? replacements[name] : loadTestDependency(require, name),
     process: runtime,
     console,
     Buffer,
@@ -141,6 +177,20 @@ test("extracts Windows cold-start and forwarded URLs without changing their payl
   assert.equal(normalizeClientProtocolUrl("jms2%3A%2F%2Fbad%ZZ"), undefined);
 });
 
+test("routes only HTTP and HTTPS asset payloads to the built-in web proxy", () => {
+  const encode = (payload: unknown) => `jms2://${Buffer.from(JSON.stringify(payload)).toString("base64")}`;
+  const http = decodeClientProtocolPayload(
+    encode({ protocol: "http", asset: { id: "asset-1" }, token: { id: "token" } })
+  );
+  const https = decodeClientProtocolPayload(encode({ protocol: "HTTPS", asset: { id: "asset-2" } }));
+  const ssh = decodeClientProtocolPayload(encode({ protocol: "ssh", asset: { id: "asset-3" } }));
+
+  assert.equal(isWebAssetClientProtocolPayload(http), true);
+  assert.equal(isWebAssetClientProtocolPayload(https), true);
+  assert.equal(isWebAssetClientProtocolPayload(ssh), false);
+  assert.equal(isWebAssetClientProtocolPayload({ protocol: "http", asset: {} }), false);
+});
+
 test("registers only jms2 and keeps the Windows development entry path as one argument", () => {
   const calls: unknown[][] = [];
   const app = {

i18n/locales/en.json

@@ -1405,6 +1405,7 @@
     "KubernetesDescription": "Kubernetes connections use the koko Kubernetes UI workspace.",
     "RemoteDesktop": "Remote desktop",
     "RemoteDesktopDescription": "RDP/VNC connections use the Lion remote desktop workspace.",
+    "ClientProxy": "Client",
     "BuiltinWebProxy": "Built-in Browser",
     "BuiltinWebProxyDescription": "Website assets use the system WebView, with traffic routed through Koko Web Proxy."
   },

i18n/locales/es.json

@@ -1405,6 +1405,7 @@
     "KubernetesDescription": "Las conexiones K8s usan el workspace de Kubernetes UI de koko.",
     "RemoteDesktop": "Escritorio remoto",
     "RemoteDesktopDescription": "Las conexiones RDP/VNC usan el workspace de escritorio remoto de Lion.",
+    "ClientProxy": "Cliente",
     "BuiltinWebProxy": "Navegador integrado",
     "BuiltinWebProxyDescription": "Los activos de sitios web usan el WebView del sistema y el tráfico pasa por Koko Web Proxy."
   },

i18n/locales/fr.json

@@ -1405,6 +1405,7 @@
     "KubernetesDescription": "Les connexions Kubernetes utilisent l’espace d’interface Kubernetes Koko.",
     "RemoteDesktop": "Bureau distant",
     "RemoteDesktopDescription": "Les connexions RDP/VNC utilisent l’espace de bureau distant Lion.",
+    "ClientProxy": "Client",
     "BuiltinWebProxy": "Navigateur intégré",
     "BuiltinWebProxyDescription": "Les actifs web utilisent la WebView du système, avec un trafic acheminé via Koko Web Proxy."
   },

i18n/locales/ja.json

@@ -1405,6 +1405,7 @@
     "KubernetesDescription": "K8s 接続は koko Kubernetes UI workspace を使用します。",
     "RemoteDesktop": "リモートデスクトップ",
     "RemoteDesktopDescription": "RDP/VNC 接続は Lion リモートデスクトップ workspace を使用します。",
+    "ClientProxy": "クライアント",
     "BuiltinWebProxy": "内蔵ブラウザ",
     "BuiltinWebProxyDescription": "Website 資産はシステム WebView を使用し、トラフィックは Koko Web Proxy 経由で統一します。"
   },

i18n/locales/ko.json

@@ -1405,6 +1405,7 @@
     "KubernetesDescription": "K8s 연결은 koko Kubernetes UI workspace를 사용합니다.",
     "RemoteDesktop": "원격 데스크톱",
     "RemoteDesktopDescription": "RDP/VNC 연결은 Lion 원격 데스크톱 workspace를 사용합니다.",
+    "ClientProxy": "클라이언트",
     "BuiltinWebProxy": "내장 브라우저",
     "BuiltinWebProxyDescription": "Website 자산은 시스템 WebView를 사용하며 트래픽은 Koko Web Proxy를 통해 전달됩니다."
   },

i18n/locales/pt_br.json

@@ -1405,6 +1405,7 @@
     "KubernetesDescription": "Conexões Kubernetes usam o workspace da UI Kubernetes do koko.",
     "RemoteDesktop": "Área de trabalho remota",
     "RemoteDesktopDescription": "Conexões RDP/VNC usam o workspace de área de trabalho remota do Lion.",
+    "ClientProxy": "Cliente",
     "BuiltinWebProxy": "Navegador integrado",
     "BuiltinWebProxyDescription": "Ativos de website usam o WebView do sistema, com o tráfego roteado pelo Koko Web Proxy."
   },