@linxin666/dsh-remote-web-ui 0.3.12 → 0.3.14

package/src/client/RemoteSettingsCard.tsx

@@ -9,7 +9,7 @@ import type { InjectFace, PropsLocale, PropsRuntime } from '@deepseek-ai/dsh-cli
 import type { SettingsScope } from '@deepseek-ai/dsh-client-ui-settings/client'
 import type { SnapshotStore } from '@deepseek-ai/dsh-client-store'
 import { PluginSettingsCard, ValueField, BooleanField } from './PluginSettingsCard.tsx'
-import { CardForm, booleanField, numberField, textField, type CardActions, type CardShell, type FieldState as CardFieldState } from './settings-form.ts'
+import { CardForm, booleanField, numberField, secretField, textField, type CardActions, type CardShell, type FieldState as CardFieldState } from './settings-form.ts'
 import { readLanBindStatus, type LanBindFrame } from './pair-api.ts'
 import type { TranslateNS } from '@deepseek-ai/dsh-client-ui-slots'
 
@@ -33,6 +33,18 @@ export interface RemoteSettings {
   publicBaseUrl?: string
   /** When on, the plugin runs its own Cloudflare quick tunnel automatically. */
   autoTunnel?: boolean
+  /**
+   * Cloudflare named-tunnel token: when set (and autoTunnel is off), the
+   * plugin runs the named tunnel toward the fixed public hostname — a phone
+   * paired once keeps its session across restarts.
+   */
+  tunnelToken?: string
+  /**
+   * Stable-origin relay: when on (default), the quick tunnel is fronted by a
+   * fixed `<id>.dsh-market.com` subdomain so the phone's bookmark and
+   * pairing cookie survive restarts without any setup.
+   */
+  relay?: boolean
   /**
    * LAN bind toggle: once flipped, the plugin manages the profile patch's
    * webserver block (0.0.0.0 / 127.0.0.1) and the host firewall rule.
@@ -60,6 +72,10 @@ export interface RemoteSettingsCardState extends CardShell {
   publicBaseUrl: CardFieldState
   /** Auto public tunnel switch. */
   autoTunnel: CardFieldState
+  /** Named-tunnel token (stored redacted by the Host). */
+  tunnelToken: CardFieldState
+  /** Stable-origin relay switch. */
+  relay: CardFieldState
   /** LAN bind toggle. */
   lanBind: CardFieldState
 }
@@ -89,6 +105,8 @@ export class RemoteSettingsCardController {
       booleanField('requirePairingForLan'),
       textField('publicBaseUrl'),
       booleanField('autoTunnel'),
+      secretField('tunnelToken'),
+      booleanField('relay'),
       booleanField('lanBind'),
     ])
     this.store = this.form.bind(() => this.projection())
@@ -106,6 +124,8 @@ export class RemoteSettingsCardController {
       requirePairingForLan: this.form.field('requirePairingForLan'),
       publicBaseUrl: this.form.field('publicBaseUrl'),
       autoTunnel: this.form.field('autoTunnel'),
+      tunnelToken: this.form.field('tunnelToken'),
+      relay: this.form.field('relay'),
       lanBind: this.form.field('lanBind'),
     }
   }
@@ -253,6 +273,28 @@ export function RemoteSettingsCard(props: RemoteSettingsCardProps) {
         onEdit={(text) => { props.edit('autoTunnel', text) }}
         onReset={() => { props.resetField('autoTunnel') }}
       />
+      <ValueField
+        id="settings-remote-tunnel-token"
+        label={t('settings.tunnelToken')}
+        hint={t('settings.tunnelTokenHint')}
+        placeholder="eyJ..."
+        {...fieldProps}
+        {...state.tunnelToken}
+        onEdit={(text) => { props.edit('tunnelToken', text) }}
+        onReset={() => { props.resetField('tunnelToken') }}
+      />
+      <BooleanField
+        id="settings-remote-relay"
+        label={t('settings.relay')}
+        hint={t('settings.relayHint')}
+        inheritLabel={t('settings.inherit')}
+        onLabel={t('settings.on')}
+        offLabel={t('settings.off')}
+        {...fieldProps}
+        {...state.relay}
+        onEdit={(text) => { props.edit('relay', text) }}
+        onReset={() => { props.resetField('relay') }}
+      />
       <LanBindStatus t={t} />
       <BooleanField
         id="settings-remote-lan-bind"

package/src/client/locales.ts

@@ -65,6 +65,8 @@ export const zh = {
   'tunnel.starting': '公网隧道启动中，二维码将自动变为公网链接…',
   'tunnel.failed': '公网隧道启动失败：{error}',
   'tunnel.unknownError': '未知错误',
+  'relay.registering': '正在把临时隧道同步到固定域名（<id>.dsh-market.com）…',
+  'relay.failed': '固定域名同步失败：{error}。正在自动重试，期间二维码可能使用临时地址。',
   'close.label': '关闭远程访问面板',
   // 插件设置卡片（settings.plugin.item 席位）。
   'settings.title': '远程访问设置',
@@ -84,9 +86,13 @@ export const zh = {
   'settings.requirePairingForLan': '局域网访问要求配对',
   'settings.requirePairingForLanHint': '开启：非本机回环的桌面 Web GUI 改走门控的 /remote，必须携带有效配对 Cookie；关闭：桌面继续走普通路径（仅在该来源已被 SDK 信任时有意义），配对只管理令牌与状态。',
   'settings.publicBaseUrl': '公网地址（可选）',
-  'settings.publicBaseUrlHint': '内网穿透的公网地址，如 Cloudflare Tunnel：https://xxx.trycloudflare.com。填写后二维码将生成公网链接，手机不在同一网络也能配对；留空则仅局域网可用。',
+  'settings.publicBaseUrlHint': '内网穿透的公网地址，如 Cloudflare Tunnel：https://xxx.trycloudflare.com；固定域名隧道（下方令牌）也填这里。填写后二维码将生成公网链接，手机不在同一网络也能配对；留空则仅局域网可用。',
   'settings.autoTunnel': '自动公网隧道',
-  'settings.autoTunnelHint': '开启后插件自动启动 Cloudflare quick tunnel（无需安装任何工具），并自动更新公网地址与信任配置，手机随时可用公网配对；关闭时使用上方手动填写的公网地址。',
+  'settings.autoTunnelHint': '开启后插件自动启动 Cloudflare quick tunnel（无需安装任何工具），并自动更新公网地址与信任配置，手机随时可用公网配对；注意临时域名每次重启都会变化，手机需重新扫码。开启时忽略下方固定隧道令牌与上方手动公网地址。',
+  'settings.tunnelToken': '固定域名隧道令牌（Cloudflare Tunnel）',
+  'settings.tunnelTokenHint': '填入 Cloudflare 命名隧道的 Token（即 cloudflared tunnel run --token 的值），插件会自动运行该隧道：公共主机名固定不变，手机配对一次后重启也无需重新配对。需先在 Cloudflare 控制台把公共主机名映射到 http://127.0.0.1:<端口>，并在上方"公网地址"填写同一域名。优先级低于"自动公网隧道"。',
+  'settings.relay': '固定域名中继（推荐开启）',
+  'settings.relayHint': '开启后自动隧道会额外注册一个固定不变的公网子域名（<id>.dsh-market.com，由 dsh-market 边缘中继到你的临时隧道），手机配对一次后重启无需重新扫码，二维码与书签地址永远不变。流量经由 dsh-market 边缘转发（与临时隧道相同的信任面）；关闭则回退为纯临时地址，每次重启需重新配对。仅对"自动公网隧道"生效。',
   'settings.lanBind': '局域网访问（绑定 0.0.0.0）',
   'settings.lanBindHint': '开启后插件把绑定默认改写为 0.0.0.0 并写入 profile 补丁（显式 --host 仍优先），同时维护主机防火墙放行（Windows/Linux；macOS 无需管理）；关闭回退 127.0.0.1。绑定变化通常在重启 dsh web 后生效。',
   'lan.cardTitle': '局域网访问',
@@ -229,6 +235,8 @@ export const en = {
   'tunnel.starting': 'The public tunnel is starting; the QR code will switch to a public link shortly…',
   'tunnel.failed': 'The public tunnel failed to start: {error}',
   'tunnel.unknownError': 'unknown error',
+  'relay.registering': 'Syncing the ephemeral tunnel to the stable hostname (<id>.dsh-market.com)…',
+  'relay.failed': 'Stable-hostname sync failed: {error}. Retrying automatically; the QR may use the ephemeral address meanwhile.',
   'close.label': 'Close remote access panel',
   // Plugin settings card (the `settings.plugin.item` seat).
   'settings.title': 'Remote access settings',
@@ -248,9 +256,13 @@ export const en = {
   'settings.requirePairingForLan': 'Require pairing for LAN access',
   'settings.requirePairingForLanHint': 'On: a desktop Web GUI at a non-loopback origin rides the gated /remote channel and must carry a live paired-device cookie. Off: the desktop stays on its original paths (only useful when that origin is already trusted) and pairing only manages tokens/status.',
   'settings.publicBaseUrl': 'Public address (optional)',
-  'settings.publicBaseUrlHint': 'The public URL of a tunnel in front of this server, e.g. a Cloudflare Tunnel: https://xxx.trycloudflare.com. When set, the QR link is built from it so a phone anywhere can pair; leave blank for LAN-only usage.',
+  'settings.publicBaseUrlHint': 'The public URL of a tunnel in front of this server, e.g. a Cloudflare Tunnel: https://xxx.trycloudflare.com; a fixed-hostname tunnel (token below) also goes here. When set, the QR link is built from it so a phone anywhere can pair; leave blank for LAN-only usage.',
   'settings.autoTunnel': 'Auto public tunnel',
-  'settings.autoTunnelHint': 'When on, the plugin runs its own Cloudflare quick tunnel (no tool installation needed) and keeps the public address and trust config in sync automatically, so a phone anywhere can pair at any time; when off, the manually entered public address above applies.',
+  'settings.autoTunnelHint': 'When on, the plugin runs its own Cloudflare quick tunnel (no tool installation needed) and keeps the public address and trust config in sync automatically, so a phone anywhere can pair at any time; note the ephemeral hostname changes on every restart, so phones must scan again. The named-tunnel token below and the manual public address above are ignored while this is on.',
+  'settings.tunnelToken': 'Fixed-hostname tunnel token (Cloudflare Tunnel)',
+  'settings.tunnelTokenHint': 'Paste a Cloudflare named-tunnel token (the value of cloudflared tunnel run --token) and the plugin runs the tunnel itself: the public hostname stays fixed, so a phone pairs once and never again across restarts. First map the public hostname to http://127.0.0.1:<port> in the Cloudflare dashboard and enter the same hostname as the public address above. Lower precedence than the auto quick tunnel.',
+  'settings.relay': 'Stable-hostname relay (recommended)',
+  'settings.relayHint': 'When on, the auto tunnel additionally registers a never-changing public subdomain (<id>.dsh-market.com, relayed by the dsh-market edge to your ephemeral tunnel), so a phone pairs once and the QR and bookmark stay valid across restarts. Traffic transits the dsh-market edge (the same trust point as the ephemeral tunnel); turn off to fall back to the raw ephemeral address, which needs re-pairing after every restart. Applies to the auto public tunnel only.',
   'settings.lanBind': 'LAN access (bind 0.0.0.0)',
   'settings.lanBindHint': 'When on, the plugin writes a managed block into the profile patch defaulting the bind to 0.0.0.0 (an explicit --host flag still wins), and maintains the matching host firewall rule (Windows/Linux; other platforms need none). When off, the block pins 127.0.0.1. The bind change usually takes effect after dsh web restarts.',
   'lan.cardTitle': 'LAN access',

package/src/client/pair-api.ts

@@ -62,6 +62,15 @@ export interface TunnelStatusFrame {
   error?: string
 }
 
+/** One relay-registry status frame (absent while the relay is not in play). */
+export interface RelayStatusFrame {
+  state: 'off' | 'registering' | 'running' | 'failed'
+  /** The stable relay origin, once registered. */
+  url?: string
+  /** Human-readable failure detail of the last sync attempt. */
+  error?: string
+}
+
 /** One /api posture frame (host half probe; see src/posture.ts). */
 export interface PostureFrame {
   checkedAt: number
@@ -81,6 +90,8 @@ export interface PairStateFrame {
   devices?: DeviceFrame[]
   /** Auto-tunnel status, while the auto-tunnel feature is active. */
   tunnel?: TunnelStatusFrame
+  /** Relay-registry status, while the stable-origin relay is in play. */
+  relay?: RelayStatusFrame
   /** Latest /api fence posture probe, once a round has completed. */
   posture?: PostureFrame
 }

package/src/client/remote-channel.ts

@@ -11,8 +11,6 @@
  * - the pairing routes (`/api/pair/*`) stay where they are — accept must
  *   work BEFORE a device is paired;
  * - the update endpoints (`/api/update/*`) stay loopback-only;
- * - desktop-launcher create/shutdown (`/api/dsh-desktop-launcher/*`) stay
- *   loopback-only (host-local files and process exit);
  * - the family settings bridge (`/api/dsh-web-ui-settings/*`) stays
  *   loopback-only (same plane as SDK settings.*);
  * - `/api/*` (SDK methods and `/api/<plugin>/...` plugin namespaces),
@@ -77,7 +75,6 @@ export function isLoopbackHostname(hostname: string): boolean {
 export function shouldRewriteFetchPath(pathname: string): boolean {
   if (pathname.startsWith(RULES.pairPrefix)) return false
   if (pathname.startsWith(RULES.updatePrefix)) return false
-  if (pathname === RULES.desktopLauncherPrefix || pathname.startsWith(`${RULES.desktopLauncherPrefix}/`)) return false
   if (pathname === RULES.settingsBridgePrefix || pathname.startsWith(`${RULES.settingsBridgePrefix}/`)) return false
   if (pathname.startsWith(RULES.apiPrefix)) return true
   if (pathname.startsWith(RULES.sidebarPrefix) || pathname === '/sidebar') return true

package/src/client/settings-card.module.css

@@ -72,7 +72,10 @@
 }
 
 .description {
-  color: var(--dsw-alias-label-tertiary);
+  /* Secondary, not tertiary: skins whose tertiary token is tuned for large
+     print leave 12-13px hint text below readable contrast (orca-link #778399
+     on cream measures ~3.4:1). */
+  color: var(--dsw-alias-label-secondary);
   font-size: 13px;
   line-height: 1.5;
 }
@@ -106,7 +109,7 @@
 }
 
 .readOnly {
-  color: var(--dsw-alias-label-tertiary);
+  color: var(--dsw-alias-label-secondary);
   margin: 12px 0 0;
   font-size: 12px;
   line-height: 1.5;
@@ -130,7 +133,10 @@
 
 .failed {
   min-width: 0;
-  color: var(--dsw-alias-label-error);
+  /* The suite's error alias is state-error-primary; a label-error token does
+     not exist, so the var() would resolve to nothing and the message would
+     inherit the ink color, losing the failure signal. */
+  color: var(--dsw-alias-state-error-primary, #b42318);
   flex: 1;
   margin: 0;
   font-size: 12px;
@@ -278,7 +284,7 @@
 }
 
 .inputInvalid {
-  border: 1px solid var(--dsw-alias-label-error);
+  border: 1px solid var(--dsw-alias-state-error-primary, #b42318);
   background: var(--dsw-alias-bg-layer-3);
   height: 34px;
   font: inherit;
@@ -290,9 +296,9 @@
 }
 
 .inputInvalid:focus-visible {
-  outline: 2px solid var(--dsw-alias-label-error);
+  outline: 2px solid var(--dsw-alias-state-error-primary, #b42318);
   outline-offset: 1px;
-  border-color: var(--dsw-alias-label-error);
+  border-color: var(--dsw-alias-state-error-primary, #b42318);
 }
 
 .selectWrap {
@@ -384,14 +390,14 @@
 }
 
 .invalid {
-  color: var(--dsw-alias-label-error);
+  color: var(--dsw-alias-state-error-primary, #b42318);
   margin: 0;
   font-size: 12px;
   line-height: 1.5;
 }
 
 .hint {
-  color: var(--dsw-alias-label-tertiary);
+  color: var(--dsw-alias-label-secondary);
   margin: 0;
   font-size: 12px;
   line-height: 1.5;

package/src/index.ts

@@ -32,6 +32,8 @@ import { claimPostureKey, postureTargets, probePosture, releasePostureKey } from
 import { lanIPv4Addresses } from './lan.ts'
 import { ensureFirewallRule, firewallSummary, removeFirewallRule } from './firewall.ts'
 import { lanBindState, writeLanBind } from './lan-bind.ts'
+import { isHttpUrl, tunnelPlanOf } from './tunnel-plan.ts'
+import { loadRelayIdentity, RelayRegistrar, type RelayState } from './relay-registry.ts'
 import { desiredBindHost, desiredBindPort, firewallActionNeeded, pendingRestartOf, type AppliedFirewallState, type StartupFacts } from './lan-bind-plan.ts'
 import { createInnerAuth } from './inner-auth.ts'
 import { TunnelManager, type TunnelInfo } from './tunnel.ts'
@@ -136,9 +138,34 @@ export interface Config {
    * cloudflared binary ships with the package — no user-side install) and
    * feeds the minted public URL into the QR base and the phone-facing
    * pairing fence dynamically, so phones anywhere can pair without any manual
-   * tunnel setup. The manual `publicBaseUrl` is ignored while this is on.
+   * tunnel setup. The minted hostname changes on every start, so a paired
+   * phone must re-pair after each restart. The manual `publicBaseUrl` and
+   * `tunnelToken` are ignored while this is on.
    */
   autoTunnel?: boolean
+  /**
+   * Cloudflare named-tunnel token (`cloudflared tunnel run --token <t>`).
+   * When set (and `autoTunnel` is off), the plugin runs the named tunnel
+   * itself — same binary, same lifecycle management — toward the fixed
+   * public hostname configured in the Cloudflare dashboard. Because that
+   * hostname never changes, a paired phone keeps its bookmark and its
+   * pairing cookie across `dsh web` restarts: pair once, never again.
+   * Requires `publicBaseUrl` to name that same hostname (the token does not
+   * carry it); without a valid `publicBaseUrl` the tunnel stays off and a
+   * warning explains what is missing. Treated as a secret: the settings
+   * surface stores it redacted.
+   */
+  tunnelToken?: string
+  /**
+   * Stable-origin relay: when on (default), the quick tunnel is fronted by a
+   * fixed `https://<id>.dsh-market.com` subdomain (the dsh-market worker's
+   * registry), so the phone's bookmark and pairing cookie survive `dsh web`
+   * restarts without any user setup. Traffic transits the dsh-market edge
+   * (the same trust point as the quick tunnel itself); turn off to fall back
+   * to the raw ephemeral quick URL. Named tunnels keep their dashboard
+   * hostname and never touch the relay.
+   */
+  relay?: boolean
   /**
    * LAN bind toggle. When the user flips it (true or false) the plugin
    * writes the managed webserver block into the profile patch — true pins
@@ -174,6 +201,8 @@ export const Config: z<Config> = z.object({
   publicBaseUrl: z.string(),
   devicesFile: z.string(),
   autoTunnel: z.boolean().default(false),
+  tunnelToken: z.string().role('secret'),
+  relay: z.boolean().default(true),
   lanBind: z.boolean(),
   profile: z.string().pattern(/^[A-Za-z0-9][A-Za-z0-9._-]*$/),
   enabled: z.boolean().default(true),
@@ -187,11 +216,12 @@ const SWEEP_INTERVAL_MS = 10_000
  * which legitimately resolves to `undefined` when unset (the schema keeps it
  * optional, so `Required` alone would over-narrow it to `string`).
  */
-type ResolvedConfig = Required<Omit<Config, 'publicBaseUrl' | 'devicesFile' | 'lanBind' | 'profile'>> & {
+type ResolvedConfig = Required<Omit<Config, 'publicBaseUrl' | 'devicesFile' | 'lanBind' | 'profile' | 'tunnelToken'>> & {
   publicBaseUrl: string | undefined
   devicesFile: string
   /** undefined until the user flips the toggle once; undefined never writes the patch. */
   lanBind: boolean | undefined
+  tunnelToken: string | undefined
   profile: string
 }
 
@@ -231,6 +261,8 @@ const DEFAULTS: ResolvedConfig = {
   publicBaseUrl: undefined,
   devicesFile: defaultDevicesFile(),
   autoTunnel: false,
+  tunnelToken: undefined,
+  relay: true,
   lanBind: undefined,
   profile: process.env.DSH_PROFILE ?? 'web',
   enabled: true,
@@ -254,6 +286,8 @@ function applyImpl(ctx: Context, config?: Config): void {
     publicBaseUrl: config?.publicBaseUrl,
     devicesFile: config?.devicesFile ?? DEFAULTS.devicesFile,
     autoTunnel: config?.autoTunnel ?? DEFAULTS.autoTunnel,
+    tunnelToken: config?.tunnelToken,
+    relay: config?.relay ?? DEFAULTS.relay,
     lanBind: config?.lanBind,
     profile: config?.profile ?? process.env.DSH_PROFILE ?? DEFAULTS.profile,
     enabled: config?.enabled ?? DEFAULTS.enabled,
@@ -274,6 +308,8 @@ function applyImpl(ctx: Context, config?: Config): void {
       publicBaseUrl: value.publicBaseUrl,
       devicesFile: value.devicesFile ?? DEFAULTS.devicesFile,
       autoTunnel: value.autoTunnel ?? DEFAULTS.autoTunnel,
+      tunnelToken: value.tunnelToken,
+      relay: value.relay ?? DEFAULTS.relay,
       lanBind: value.lanBind,
       profile: value.profile ?? process.env.DSH_PROFILE ?? DEFAULTS.profile,
       enabled: value.enabled ?? DEFAULTS.enabled,
@@ -288,24 +324,89 @@ function applyImpl(ctx: Context, config?: Config): void {
   // mutation is needed here (a distributable plugin must not change the
   // harness's connection plugin).
   const tunnel = new TunnelManager()
-  let autoTunnel = resolved.autoTunnel
+  // Relay registry: one stable `<id>.dsh-market.com` subdomain per profile
+  // in front of the quick tunnel. The QR base prefers the relay origin once
+  // it is registered; until then (or when the registry is unreachable) the
+  // raw quick URL is used, exactly as before. Named tunnels keep their fixed
+  // dashboard hostname and never touch the relay.
+  let relayRegistrar: RelayRegistrar | undefined
+  let relayUrl: string | undefined
+  let rawTunnelUrl: string | undefined
+  /** The tunnel target the registrar last announced (dedupes sync re-runs). */
+  let relayAnnouncedFor: string | undefined
+  const setPublicBase = (): void => {
+    service.setPublicBaseUrl(relayUrl ?? rawTunnelUrl)
+  }
+  const disposeRelayRegistrar = (unregister: boolean = false): void => {
+    const registrar = relayRegistrar
+    relayRegistrar = undefined
+    relayUrl = undefined
+    relayAnnouncedFor = undefined
+    if (registrar === undefined) return
+    // Toggle-off removes the registry row so the stable origin stops
+    // proxying; teardown/mode changes keep the row (the phone then sees the
+    // relay's offline page instead of a dangling claim, and re-enabling
+    // reuses the same identity).
+    if (unregister) void registrar.unregister().catch(() => undefined)
+    registrar.dispose()
+  }
+  const ensureRelayRegistrar = (): RelayRegistrar | undefined => {
+    if (resolve().relay === false) return undefined
+    if (relayRegistrar === undefined) {
+      try {
+        const identity = loadRelayIdentity(resolve().profile)
+        relayRegistrar = new RelayRegistrar(identity, (state: RelayState) => {
+          service.setRelayStatus(state.state === 'off' ? undefined : state)
+          if (state.state === 'running') {
+            relayUrl = state.url
+          } else if (state.state === 'off') {
+            relayUrl = undefined
+          } else if (state.state === 'failed') {
+            // Keep the last relay URL on failures: the phone origin only
+            // breaks when the mapping itself goes stale, not when one
+            // refresh call fails. The registrar retries with backoff.
+            console.warn(`remote-web-ui: relay registration failed (${state.error}) — the stable origin may serve its offline page until the retry lands`)
+          }
+          setPublicBase()
+        })
+      } catch (error) {
+        console.warn(`remote-web-ui: relay registry unavailable (${error instanceof Error ? error.message : String(error)}) — the quick URL is the QR base`)
+      }
+    }
+    return relayRegistrar
+  }
+  const announceRelay = (registrar: RelayRegistrar, target: string): void => {
+    if (relayAnnouncedFor === target) return
+    relayAnnouncedFor = target
+    void registrar.announce(target)
+  }
+  // 'off' until a sync pass turns a mode on; the phase listener only feeds
+  // the public base while a plugin-managed tunnel (quick or named) runs.
+  let tunnelMode: 'off' | 'quick' | 'named' = resolved.autoTunnel ? 'quick' : 'off'
   tunnel.onPhase((info: TunnelInfo) => {
-    if (!autoTunnel) return
+    if (tunnelMode === 'off') return
     if (info.phase === 'running' && info.url !== undefined) {
-      service.setPublicBaseUrl(info.url)
+      rawTunnelUrl = info.url
+      setPublicBase()
       service.setTunnelStatus({ state: 'running', url: info.url })
+      const registrar = tunnelMode === 'quick' ? ensureRelayRegistrar() : undefined
+      if (registrar !== undefined) announceRelay(registrar, info.url)
       runPostureProbe()
     } else if (info.phase === 'starting') {
       // A restart mints a NEW hostname: the previous URL dies with the old
       // process, so clear it now rather than advertising a dead link.
-      service.setPublicBaseUrl(undefined)
+      rawTunnelUrl = undefined
+      relayUrl = undefined
+      setPublicBase()
       service.setTunnelStatus({ state: 'starting' })
     } else if (info.phase === 'failed') {
-      service.setPublicBaseUrl(undefined)
+      rawTunnelUrl = undefined
+      setPublicBase()
       service.setTunnelStatus(info.error === undefined ? { state: 'failed' } : { state: 'failed', error: info.error })
     }
   })
   ctx.effect(() => () => {
+    disposeRelayRegistrar()
     tunnel.dispose()
   }, 'remote-web-ui: auto tunnel')
   // The bind facts are known by now (webServer is an inject edge): the LAN
@@ -639,17 +740,54 @@ function applyImpl(ctx: Context, config?: Config): void {
         }
       }
     }
-    // The auto tunnel owns the public base while enabled: the minted URL
-    // lands in the service through the tunnel's phase listener. The manual
-    // publicBaseUrl applies only when the auto tunnel is off.
-    autoTunnel = value.autoTunnel === true
-    if (autoTunnel) {
-      if (value.publicBaseUrl !== undefined) {
-        console.warn('remote-web-ui: autoTunnel is on — ignoring the manually configured publicBaseUrl')
+    // The plugin-managed tunnels own the public base while one runs: the URL
+    // lands in the service through the tunnel's phase listener (the minted
+    // quick URL, or the named tunnel's fixed public hostname). The manual
+    // publicBaseUrl applies only when no tunnel runs.
+    const plan = tunnelPlanOf(value, ctx.webServer.port)
+    tunnelMode = plan.mode
+    if (plan.mode !== 'quick') {
+      // The relay only fronts the quick tunnel; named mode owns its fixed
+      // dashboard hostname and the off mode has no public base at all.
+      disposeRelayRegistrar()
+      if (plan.mode !== 'named') setPublicBase()
+    } else if (value.relay === false) {
+      // The relay toggle is off: no stable origin, the raw quick URL is the
+      // QR base exactly as before the relay existed.
+      disposeRelayRegistrar(true)
+      setPublicBase()
+    } else if (rawTunnelUrl !== undefined) {
+      // The relay just turned on (or the registrar is new) while the tunnel
+      // already runs: announce now — no phase event will fire for an
+      // unchanged target.
+      const registrar = ensureRelayRegistrar()
+      if (registrar !== undefined) announceRelay(registrar, rawTunnelUrl)
+    }
+    if (plan.mode === 'quick') {
+      for (const ignored of plan.ignored) {
+        console.warn(`remote-web-ui: autoTunnel is on — ignoring the configured ${ignored}`)
       }
-      tunnel.start(`http://127.0.0.1:${String(ctx.webServer.port)}`)
+      // With the relay on, the connector stamps the stable origin as the
+      // origin-side Host (`--http-host-header`): the plugin fence and the
+      // harness browser-auth are Host-bound to the relay origin, and the
+      // Workers relay cannot control the origin-side Host (fetch forces it
+      // to the URL authority). The target identity change is also what
+      // restarts a running tunnel on a relay toggle.
+      const registrar = ensureRelayRegistrar()
+      const originHostHeader = registrar === undefined ? undefined : new URL(registrar.baseUrl).host
+      tunnel.start(originHostHeader === undefined
+        ? plan.targetUrl
+        : { kind: 'quick', targetUrl: plan.targetUrl, originHostHeader })
+    } else if (plan.mode === 'named') {
+      tunnel.start({ kind: 'named', token: plan.token, publicUrl: plan.publicUrl })
     } else {
       tunnel.stop()
+      // A named-tunnel token without a usable public hostname cannot serve
+      // the QR: stay off and say exactly what is missing instead of running
+      // a tunnel nothing points at.
+      if (value.tunnelToken !== undefined && value.tunnelToken !== '') {
+        console.warn('remote-web-ui: tunnelToken is set but publicBaseUrl is missing or not a valid URL — fill the fixed public hostname of the named tunnel (e.g. https://dsh.example.com) to run it')
+      }
       // A malformed public base is ignored with a warning — LAN-only behavior
       // stays intact rather than silently minting unusable QR links.
       if (value.publicBaseUrl !== undefined && !isHttpUrl(value.publicBaseUrl)) {
@@ -724,13 +862,3 @@ function applyImpl(ctx: Context, config?: Config): void {
   })
   sync()
 }
-
-/** Whether a configured public base is a parseable http(s) URL with a host. */
-function isHttpUrl(value: string): boolean {
-  try {
-    const url = new URL(value)
-    return (url.protocol === 'http:' || url.protocol === 'https:') && url.hostname !== ''
-  } catch {
-    return false
-  }
-}

package/src/pairing.ts

@@ -103,6 +103,19 @@ export interface TunnelStatus {
   error?: string
 }
 
+/**
+ * One relay-registry status frame (undefined while the stable-origin relay
+ * is not in play: autoTunnel off, or the relay toggle disabled).
+ */
+export interface RelayStatus {
+  /** registering: a sync is in flight; running: the mapping is accepted. */
+  state: 'off' | 'registering' | 'running' | 'failed'
+  /** The stable relay origin (`https://<id>.dsh-market.com`). */
+  url?: string
+  /** Human-readable failure detail of the last sync attempt. */
+  error?: string
+}
+
 /** One snapshot frame pushed to desktop status streams. */
 export interface PairingSnapshot {
   phase: PairingPhase
@@ -114,6 +127,8 @@ export interface PairingSnapshot {
   publicUrl?: string
   /** Auto-tunnel status, while the auto-tunnel feature is active. */
   tunnel?: TunnelStatus
+  /** Relay-registry status, while the stable-origin relay is in play. */
+  relay?: RelayStatus
   /** Latest /api posture probe (undefined until the first round completes). */
   posture?: PostureSnapshot
   /** Opaque (non-secret) id of the active token (undefined when stopped/lan-required). */
@@ -202,6 +217,7 @@ export class PairingService {
   private publicBase: string | undefined
   /** Auto-tunnel status, while the auto-tunnel feature is active. */
   private tunnelStatus: TunnelStatus | undefined
+  private relayStatus: RelayStatus | undefined
   private posture: PostureSnapshot | undefined
   /** True when lastSeenAt changed since the last persist (flushed on sweep). */
   private dirty = false
@@ -339,6 +355,12 @@ export class PairingService {
     this.notify()
   }
 
+  /** Set or clear the relay-registry status frame (undefined when not in play). */
+  setRelayStatus(status: RelayStatus | undefined): void {
+    this.relayStatus = status
+    this.notify()
+  }
+
   /** Set the latest /api posture probe result (see posture.ts). */
   setPosture(snapshot: PostureSnapshot | undefined): void {
     this.posture = snapshot
@@ -497,6 +519,7 @@ export class PairingService {
       lanAddresses: [...this.lanBases.keys()],
       ...(this.publicBase !== undefined ? { publicUrl: this.publicBase } : {}),
       ...(this.tunnelStatus !== undefined ? { tunnel: this.tunnelStatus } : {}),
+      ...(this.relayStatus !== undefined ? { relay: this.relayStatus } : {}),
       ...(this.posture !== undefined ? { posture: this.posture } : {}),
       ...(token !== undefined ? { tokenId: token.record.id, tokenExpiresAt: token.record.expiresAt } : {}),
       deviceCount: this.devices.size,
@@ -588,6 +611,7 @@ function snapshotsEqual(a: PairingSnapshot, b: PairingSnapshot): boolean {
     && sameStrings(a.lanAddresses, b.lanAddresses)
     && a.publicUrl === b.publicUrl
     && tunnelEqual(a.tunnel, b.tunnel)
+    && relayEqual(a.relay, b.relay)
     && a.tokenId === b.tokenId
     && a.tokenExpiresAt === b.tokenExpiresAt
     && a.deviceCount === b.deviceCount
@@ -614,6 +638,12 @@ function tunnelEqual(a: TunnelStatus | undefined, b: TunnelStatus | undefined):
     && a.state === b.state && a.url === b.url && a.error === b.error)
 }
 
+/** Relay frame equality (same shape as the tunnel frame). */
+function relayEqual(a: RelayStatus | undefined, b: RelayStatus | undefined): boolean {
+  return a === b || (a !== undefined && b !== undefined
+    && a.state === b.state && a.url === b.url && a.error === b.error)
+}
+
 /** Element-wise string list equality (interface order is meaningful). */
 function sameStrings(a: readonly string[], b: readonly string[]): boolean {
   return a.length === b.length && a.every((value, index) => value === b[index])