@deepseek-ai/dsh-web-app 0.2.0-rc.2 → 0.2.1-alpha.2

package/lib/index.js

@@ -1,11 +1,13 @@
+import { t as parsePublicUrl } from "./public-url-D_dMK-yI.js";
 import { createRequire } from "node:module";
 import { spawn } from "node:child_process";
+import { isIP } from "node:net";
 import { dirname, join } from "node:path";
-import { networkInterfaces } from "node:os";
 import { fileURLToPath } from "node:url";
 import z from "@deepseek-ai/schemastery";
 import { addHarnessSourceSection, auditStartupEntries } from "@deepseek-ai/dsh-app-boot";
 import * as FrontendStatic from "@deepseek-ai/dsh-host-frontend-static";
+import { isLoopbackHost, normalizeBindAddress } from "@deepseek-ai/dsh-host-webserver";
 import { launchEnvironmentOf, launchedThroughSsh } from "@deepseek-ai/dsh-launch-environment";
 import { scrubbedParentEnv } from "@deepseek-ai/dsh-subprocess";
 //#region lib/types/index.js
@@ -16,9 +18,10 @@ import { scrubbedParentEnv } from "@deepseek-ai/dsh-subprocess";
 * the built frontend dist (workspace knowledge of this bundle, never user
 * config), mounts the `frontend-static` fallback owner over it, registers the
 * harness-source and web-surface prompt sections, the bash-visible web runtime
-* variable, the process-token URL line, and the default-browser handoff. The
-* model and shell retain the clean URL. App command-line values arrive through
-* the `webStartup` service expressions in the bundle patch.
+* variable, the process-token URL line, and the default-browser handoff. An
+* advertised `publicUrl` replaces the published bind-address URL. Non-loopback
+* HTTP binds trigger an exposure warning. App command-line values arrive
+* through the `webStartup` service expressions in the bundle patch.
 * @module @deepseek-ai/dsh-web-app
 */
 /** Stable Cordis plugin name. */
@@ -26,21 +29,16 @@ const name = "web-app";
 /** This dsh installation's root, from either this package's source or built entry. */
 const SOURCE_ROOT = fileURLToPath(new URL("../../../..", import.meta.url));
 const ANNOUNCED_ROOTS = /* @__PURE__ */ new WeakSet();
-/** Runtime service that releases Web rows after bind-dependent values resolve. */
-const WEB_RUNTIME_SERVICE = "webRuntime";
 /** Services required before the web runtime can mount. */
 const inject = ["webServer"];
 const Config = z.object({
 	openBrowser: z.boolean().default(true),
 	printUrl: z.boolean().default(true),
 	surfaceContext: z.boolean().default(true),
-	trustedHosts: z.array(String).default([])
+	publicUrl: z.transform(z.string(), (value) => parsePublicUrl(value).href)
 });
-/** Environment variable naming the canonical local URL of this Web GUI. */
+/** Environment variable naming the advertised URL of this Web GUI. */
 const DSH_WEB_URL = "DSH_WEB_URL";
-const LOOPBACK_HOST = "127.0.0.1";
-/** The webserver schema's all-interfaces bind literal. */
-const ALL_INTERFACES_HOST = "0.0.0.0";
 const BROWSER_OPENER_MODULE = import.meta.resolve("open");
 const BROWSER_OPENER_PROGRAM = `
 try {
@@ -71,32 +69,46 @@ try {
 }
 `;
 /**
-* Resolve one LAN-trust snapshot from the active server bind.
-*
-* Derived entries are port-less IP literals: DNS rebinding needs an
-* attacker-controlled name, while an IP-literal Host is safe on any port and
-* an OS-assigned port is unknowable before bind.
-* @param bindHost - the active webserver bind host.
-* @param extra - explicit `--trusted-host` values, in argument order.
-* @returns the LAN display addresses and invocation-derived fence authorities.
+* Local root URL of the active Web server, using the browser-compatible form
+* of its bind address and brackets for IPv6 literals. Non-loopback binds such
+* as a container's Pod address advertise that address.
+* @throws when the runtime resolves without a bound webServer, or when the bind
+*   address has no URL form (see {@link advertisedBindHost}).
 */
-function resolveLanTrust(bindHost, extra) {
-	const lanAddresses = bindHost === ALL_INTERFACES_HOST ? Object.values(networkInterfaces()).flat().filter((iface) => iface !== void 0 && iface.family === "IPv4" && !iface.internal).map((iface) => iface.address) : [];
-	return {
-		lanAddresses,
-		trustedHosts: [...lanAddresses, ...extra]
-	};
+function localWebUrl(ctx) {
+	const webServer = ctx.get("webServer");
+	const port = webServer?.port;
+	if (webServer === void 0 || port === void 0) throw new Error("web-app: webServer service missing while resolving Web runtime");
+	const host = advertisedBindHost(webServer.host);
+	return `${webServer.protocol}//${isIP(host) === 6 ? `[${host}]` : host}:${String(port)}`;
+}
+/**
+* Bind address in a URL. Loopback addresses use their canonical address text,
+* so browsers treat them as local, trustworthy origins: a genuinely mapped
+* literal such as `::ffff:127.0.0.1` reads as `127.0.0.1`, and a dotted-quad
+* tail reads as the address it names, so `::0.0.0.1` reads as `::1` rather
+* than as `0.0.0.1`. Interface zone IDs cannot appear in a URL; only a
+* redundant loopback zone can be dropped.
+* @param host - webserver bind address.
+* @returns the zone-free URL host.
+* @throws when a non-loopback zone requires an explicit public URL.
+*/
+function advertisedBindHost(host) {
+	const zoneAt = host.indexOf("%");
+	const bare = zoneAt === -1 ? host : host.slice(0, zoneAt);
+	if (isLoopbackHost(bare)) return normalizeBindAddress(bare);
+	if (zoneAt === -1) return host;
+	throw new Error(`web-app: bind address ${JSON.stringify(host)} carries an interface zone id, which no URL can express; pass --public-url with the root browsers actually reach it through`);
+}
+/** Resolve the advertised root: this plugin's canonical `publicUrl`, or the bind-address URL (loopback when bound to loopback). */
+function appRootUrl(ctx, publicUrl) {
+	if (publicUrl !== void 0) return publicUrl;
+	return localWebUrl(ctx);
 }
 /** Model-visible orientation and acceptance boundary for sessions created through `dsh web`. */
 function webSurfacePrompt(webUrl) {
 	return `You are interacting with the user through the DeepSeek Harness Web GUI at ${webUrl}. When the user refers to "this page", "this GUI", or "this app" without naming another target, they mean this GUI. The browser provides no implicit DOM, route, or screenshot context. The client-plugin HMR receiver is active, but client-plugin changes reload without a refresh only while \`pnpm run dev:web\` is also running from this same checkout to rebuild their bundles; verify that watcher before promising automatic updates. Every other change — the apps/web shell and plain packages — requires rebuilding the affected Web artifacts and verifying this existing URL after a page refresh. Starting another server does not update this GUI. The apps/web Vite entry builds the shell but is not a standalone application because only dsh web injects window.__DSH_BOOT__. Do not start a replacement server unless the user asks; if one is needed, use a managed background job and verify its exact URL.`;
 }
-/** Resolve the canonical loopback URL from the active Web server. */
-function localWebUrl(ctx) {
-	const port = ctx.get("webServer")?.port;
-	if (port === void 0) throw new Error("web-app: webServer service missing while resolving Web runtime");
-	return `http://${LOOPBACK_HOST}:${String(port)}`;
-}
 /**
 * Dist location is workspace knowledge of this bundle: anchored on the
 * frontend package manifest, not configured. Existence is a request-time
@@ -170,9 +182,11 @@ const internals = {
 * @param config - validated {@link Config}.
 */
 function apply(ctx, config) {
-	const runtime = resolveLanTrust(ctx.webServer.host, config.trustedHosts);
+	const publicUrl = config.publicUrl ?? void 0;
+	const boundHost = ctx.webServer.host;
+	if (publicUrl === void 0) advertisedBindHost(boundHost);
+	if (ctx.webServer.protocol === "http:" && !isLoopbackHost(boundHost)) console.warn(`dsh web: listening on ${boundHost} over plain HTTP; restrict this port to a trusted proxy or network`);
 	const handoffBrowser = config.openBrowser && !launchedThroughSsh(launchEnvironmentOf(ctx));
-	ctx.provide(WEB_RUNTIME_SERVICE, runtime);
 	ctx.plugin(FrontendStatic, { distIndex: internals.resolveDistIndex() });
 	if (config.surfaceContext) {
 		ctx.inject(["systemPrompt"], (promptCtx) => {
@@ -180,27 +194,24 @@ function apply(ctx, config) {
 			promptCtx.systemPrompt.section({
 				name: "app:web-surface",
 				order: promptCtx.systemPrompt.getSectionOrder("WEB_SURFACE"),
-				text: () => webSurfacePrompt(localWebUrl(promptCtx))
+				text: () => webSurfacePrompt(appRootUrl(promptCtx, publicUrl))
 			});
 		});
 		ctx.inject(["shellEnv"], (runtimeCtx) => {
 			runtimeCtx.shellEnv.register({
 				name: "web-runtime",
-				variables: { [DSH_WEB_URL]: { description: "Canonical local URL of the DeepSeek Harness Web GUI serving this session." } },
-				resolve: () => ({ [DSH_WEB_URL]: localWebUrl(runtimeCtx) })
+				variables: { [DSH_WEB_URL]: { description: "Advertised URL of the DeepSeek Harness Web GUI serving this session." } },
+				resolve: () => ({ [DSH_WEB_URL]: appRootUrl(runtimeCtx, publicUrl) })
 			});
 		});
 	}
 	if (config.printUrl || handoffBrowser) ctx.inject(["connection"], (connectionCtx) => {
 		const announceReady = () => {
 			if (ANNOUNCED_ROOTS.has(connectionCtx.root)) return;
-			const webUrl = localWebUrl(connectionCtx);
+			const webUrl = appRootUrl(connectionCtx, publicUrl);
 			const authenticatedUrl = connectionCtx.connection.authenticatedUrl(webUrl);
-			const lanCandidate = runtime.lanAddresses[0];
-			const port = connectionCtx.webServer.port;
-			const lanUrl = lanCandidate === void 0 ? void 0 : connectionCtx.connection.authenticatedUrl(`http://${lanCandidate}:${String(port)}`);
 			ANNOUNCED_ROOTS.add(connectionCtx.root);
-			if (config.printUrl) console.log(`dsh web: ${authenticatedUrl}${lanUrl === void 0 ? "" : ` (LAN: ${lanUrl})`}`);
+			if (config.printUrl) console.log(`dsh web: ${authenticatedUrl}`);
 			if (handoffBrowser) {
 				console.log("dsh web: opening the default browser; pass --no-open to disable");
 				internals.openBrowser(authenticatedUrl).catch((error) => {
@@ -218,4 +229,4 @@ function apply(ctx, config) {
 	});
 }
 //#endregion
-export { Config, apply, inject, internals, name, resolveLanTrust };
+export { Config, apply, inject, internals, name };

package/lib/public-url-D_dMK-yI.js

@@ -0,0 +1,29 @@
+//#region lib/types/public-url.js
+/**
+* Canonical public HTTP(S) root parsing shared by this bundle's `publicUrl`
+* config and its CLI startup provider.
+* @module @deepseek-ai/dsh-web-app/public-url
+*/
+/**
+* Parse the advertised public HTTP(S) root of a prefix-stripping proxy
+* deployment, rejecting the hazards WHATWG URL parsing would accept on its own,
+* then normalize the path to end in `/`.
+* @param value - advertised public HTTP(S) root.
+* @param label - field name or CLI flag included in rejection messages.
+* @returns the parsed URL with a trailing-slash pathname.
+* @throws when the value is not a usable advertised root, naming the reason.
+*/
+function parsePublicUrl(value, label = "publicUrl") {
+	if (/[\u0000-\u0020\u007f]/u.test(value)) throw new Error(`${label} must not contain ASCII whitespace or control characters`);
+	if (!/^https?:\/\//iu.test(value)) throw new Error(`${label} must be an absolute http or https URL of the form http(s)://host[/prefix]`);
+	if (value.includes("?") || value.includes("#")) throw new Error(`${label} must not include a query or fragment (? or #)`);
+	const [authority = ""] = value.slice(value.indexOf("://") + 3).split(/[/\\]/, 1);
+	if (authority === "") throw new Error(`${label} must name a host after http:// or https://`);
+	if (authority.includes("@")) throw new Error(`${label} must not include credentials (a username or password before @, including an empty user)`);
+	const url = URL.parse(value);
+	if (url === null) throw new Error(`${label} must be an absolute http or https URL`);
+	if (!url.pathname.endsWith("/")) url.pathname += "/";
+	return url;
+}
+//#endregion
+export { parsePublicUrl as t };

package/lib/startup.js

@@ -1,11 +1,14 @@
+import { t as parsePublicUrl } from "./public-url-D_dMK-yI.js";
+import { isWildcardHost } from "@deepseek-ai/dsh-host-webserver";
 import { Command } from "commander";
 import { parseCmdline } from "@deepseek-ai/dsh-cmdline";
 //#region lib/types/startup.js
 /**
 * The web app's command-line provider: it parses the `dsh --profile web` flag
-* family (`--host`, `--port`, `--trusted-host`, `--no-open`) and its `--help`
-* text, then provides the immutable values as {@link WEB_STARTUP_SERVICE}.
-* Ordinary rows inject that service before reading it from lazy config.
+* family (`--host`, `--port`, `--public-url`, `--trusted-host`, `--no-open`, TLS)
+* and its `--help` text, then provides the immutable values as
+* {@link WEB_STARTUP_SERVICE}. Ordinary rows inject that service before
+* reading it from lazy config.
 * @module @deepseek-ai/dsh-web-app/startup
 */
 /** Stable Cordis plugin name. */
@@ -19,30 +22,48 @@ const WEB_STARTUP_SERVICE = "webStartup";
 * @returns a fresh program, so one process can parse more than once (tests).
 */
 function webCommand() {
-	return new Command().name("dsh --profile web").description("Serve the DeepSeek Harness browser UI.").helpOption("-h, --help", "show this help").option("--host <host>", "bind host").option("--no-open", "do not open the Web UI in the default browser").option("--port <port>", "listen port; pass 0 to let the OS pick a free one").option("--trusted-host <authority...>", "extra authority the /api browser-trust fence accepts (host or host:port; repeatable)").addHelpText("after", `
+	return new Command().name("dsh --profile web").description("Serve the DeepSeek Harness browser UI.").helpOption("-h, --help", "show this help").option("--host <host>", "bind address: one concrete IPv4 or IPv6 literal of a local interface; wildcard addresses are rejected").option("--no-open", "do not open the Web UI in the default browser").option("--port <port>", "listen port; pass 0 to let the OS pick a free one").option("--public-url <url>", "advertise this HTTP(S) root in the printed, opened, web-surface, and DSH_WEB_URL forms; grants no trust").option("--trusted-host <authority...>", "extra authority the /api browser-trust fence accepts (host or host:port; repeatable)").option("--tls-cert <file>", "PEM server certificate chain; requires --tls-key").option("--tls-key <file>", "unencrypted PEM private key; requires --tls-cert").addHelpText("after", `
 Examples:
   dsh --profile web                          serve on the composed host and port
   dsh --profile web --no-open                serve without opening a browser
   dsh --profile web --port 8080              serve on another port
+  dsh --profile web --host 10.0.0.7          bind one local interface address
+  dsh --profile web --public-url https://app.example/ui/ --trusted-host app.example
+                                             advertise a prefix-stripping HTTPS proxy entry and admit its authority
+  dsh --profile web --tls-cert ./server-chain.pem --tls-key ./server-key.pem
+                                             serve HTTPS with an existing certificate and key
 `);
 }
 /**
 * Parse and provide the Web invocation as an ordinary Cordis service. The
-* command's action publishes the flags this invocation named; `--host 0.0.0.0`
-* or a non-numeric `--port` is a usage error, so on rejection (and on `--help`)
-* nothing is provided.
+* command's action publishes the flags this invocation named. Invalid flags,
+* including an unpaired TLS certificate or key, are usage errors; rejection
+* and `--help` provide no service.
 * @param ctx - plugin context carrying the command line.
 */
 function apply(ctx) {
 	const program = webCommand();
 	program.action(() => {
 		const options = program.opts();
-		if (options.host === "0.0.0.0") program.error("error: --host 0.0.0.0 is intentionally not supported yet for safety: it would expose remote code execution to the network; use 127.0.0.1 instead");
+		if (options.host !== void 0 && isWildcardHost(options.host)) program.error(`error: --host ${options.host} is an unspecified (wildcard) address, which is not supported: binding every interface would expose remote code execution to the network; bind one concrete IPv4 or IPv6 address instead`);
 		if (options.port !== void 0 && !/^\d+$/.test(options.port)) program.error(`error: --port must be a number, got ${JSON.stringify(options.port)}`);
+		let tls;
+		if (options.tlsCert !== void 0 && options.tlsKey !== void 0) tls = {
+			certFile: options.tlsCert,
+			keyFile: options.tlsKey
+		};
+		else if (options.tlsCert !== void 0 || options.tlsKey !== void 0) program.error("error: --tls-cert and --tls-key must be supplied together");
+		if (options.publicUrl !== void 0) try {
+			parsePublicUrl(options.publicUrl, "--public-url");
+		} catch (error) {
+			program.error(`error: ${error.message}`);
+		}
 		ctx.provide(WEB_STARTUP_SERVICE, {
 			openBrowser: options.open,
 			...options.host !== void 0 && { host: options.host },
 			...options.port !== void 0 && { port: Number(options.port) },
+			...options.publicUrl !== void 0 && { publicUrl: options.publicUrl },
+			...tls !== void 0 && { tls },
 			trustedHosts: options.trustedHost ?? []
 		});
 	});

package/lib/types/index.d.ts

@@ -5,9 +5,10 @@
  * the built frontend dist (workspace knowledge of this bundle, never user
  * config), mounts the `frontend-static` fallback owner over it, registers the
  * harness-source and web-surface prompt sections, the bash-visible web runtime
- * variable, the process-token URL line, and the default-browser handoff. The
- * model and shell retain the clean URL. App command-line values arrive through
- * the `webStartup` service expressions in the bundle patch.
+ * variable, the process-token URL line, and the default-browser handoff. An
+ * advertised `publicUrl` replaces the published bind-address URL. Non-loopback
+ * HTTP binds trigger an exposure warning. App command-line values arrive
+ * through the `webStartup` service expressions in the bundle patch.
  * @module @deepseek-ai/dsh-web-app
  */
 import type { Context } from '@deepseek-ai/cordis';
@@ -29,28 +30,16 @@ export interface Config {
      * orientation text would be false.
      */
     surfaceContext: boolean;
-    /** Explicit `--trusted-host` authorities from this invocation. */
-    trustedHosts: string[];
+    /**
+     * Canonical HTTP(S) root to advertise in the printed and opened URL,
+     * `DSH_WEB_URL`, and the web-surface orientation, e.g.
+     * `https://app.example/ui/`, normalized to end in `/`. Configures no routing
+     * or authentication; see [public deployments](../README.md#public-deployments).
+     * Absent or YAML `null` advertises the bind-address URL.
+     */
+    publicUrl?: string;
 }
 export declare const Config: z<Config>;
-/** Bind-dependent Web values shared by the trust fence and URL display. */
-export interface WebRuntimeValues {
-    /** LAN IPv4 literals sampled once when the server binds all interfaces. */
-    lanAddresses: string[];
-    /** LAN literals followed by explicit invocation authorities. */
-    trustedHosts: string[];
-}
-/**
- * Resolve one LAN-trust snapshot from the active server bind.
- *
- * Derived entries are port-less IP literals: DNS rebinding needs an
- * attacker-controlled name, while an IP-literal Host is safe on any port and
- * an OS-assigned port is unknowable before bind.
- * @param bindHost - the active webserver bind host.
- * @param extra - explicit `--trusted-host` values, in argument order.
- * @returns the LAN display addresses and invocation-derived fence authorities.
- */
-export declare function resolveLanTrust(bindHost: string, extra: readonly string[]): WebRuntimeValues;
 /** Test hooks for the built dist and native browser handoff; production never mutates them. */
 export declare const internals: {
     resolveDistIndex: () => string;

package/lib/types/public-url.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Canonical public HTTP(S) root parsing shared by this bundle's `publicUrl`
+ * config and its CLI startup provider.
+ * @module @deepseek-ai/dsh-web-app/public-url
+ */
+/**
+ * Parse the advertised public HTTP(S) root of a prefix-stripping proxy
+ * deployment, rejecting the hazards WHATWG URL parsing would accept on its own,
+ * then normalize the path to end in `/`.
+ * @param value - advertised public HTTP(S) root.
+ * @param label - field name or CLI flag included in rejection messages.
+ * @returns the parsed URL with a trailing-slash pathname.
+ * @throws when the value is not a usable advertised root, naming the reason.
+ */
+export declare function parsePublicUrl(value: string, label?: string): URL;
+//# sourceMappingURL=public-url.d.ts.map

package/lib/types/startup.d.ts

@@ -1,11 +1,13 @@
 /**
  * The web app's command-line provider: it parses the `dsh --profile web` flag
- * family (`--host`, `--port`, `--trusted-host`, `--no-open`) and its `--help`
- * text, then provides the immutable values as {@link WEB_STARTUP_SERVICE}.
- * Ordinary rows inject that service before reading it from lazy config.
+ * family (`--host`, `--port`, `--public-url`, `--trusted-host`, `--no-open`, TLS)
+ * and its `--help` text, then provides the immutable values as
+ * {@link WEB_STARTUP_SERVICE}. Ordinary rows inject that service before
+ * reading it from lazy config.
  * @module @deepseek-ai/dsh-web-app/startup
  */
 import type { Context } from '@deepseek-ai/cordis';
+import { type TlsConfig } from '@deepseek-ai/dsh-host-webserver';
 /** Stable Cordis plugin name. */
 export declare const name = "web-startup";
 /** Services required before the flags can be resolved. */
@@ -20,14 +22,21 @@ export interface WebStartupValues {
     host?: string;
     /** `--port`, absent when the invocation did not name one. */
     port?: number;
+    /**
+     * `--public-url`, absent when not specified: the advertised HTTP(S) root.
+     * See [public deployments](../README.md#public-deployments).
+     */
+    publicUrl?: string;
     /** Explicit `--trusted-host` authorities, in argument order. */
     trustedHosts: string[];
+    /** Server certificate chain and unencrypted private key supplied together. */
+    tls?: TlsConfig;
 }
 /**
  * Parse and provide the Web invocation as an ordinary Cordis service. The
- * command's action publishes the flags this invocation named; `--host 0.0.0.0`
- * or a non-numeric `--port` is a usage error, so on rejection (and on `--help`)
- * nothing is provided.
+ * command's action publishes the flags this invocation named. Invalid flags,
+ * including an unpaired TLS certificate or key, are usage errors; rejection
+ * and `--help` provide no service.
  * @param ctx - plugin context carrying the command line.
  */
 export declare function apply(ctx: Context): void;