@linxin666/dsh-remote-web-ui 0.2.8 → 0.3.0

package/src/paired-model-catalog.ts

@@ -0,0 +1,224 @@
+/** Paired-only model discovery and adoption routes; generic privileged RPCs stay loopback-only. */
+import type { IncomingMessage, ServerResponse } from 'node:http'
+import type { ApiProxy, ModelProviderGroup, RpcId, RpcResponse, SettingsNamespaceView } from '@deepseek-ai/dsh-host-apiproxy/api'
+import type { WebRoute } from '@deepseek-ai/dsh-host-webserver'
+import { z } from 'zod'
+import type { PairingService } from './pairing.ts'
+import { readCookie } from './gate.ts'
+import { readBoundedJson, writeJson } from './http.ts'
+import { isTrustedApiRequest, publicHostOf } from './routes.ts'
+
+const MAX_BODY_BYTES = 16 * 1024
+const MAX_IDENTIFIER_LENGTH = 160
+const MAX_DISPLAY_NAME_LENGTH = 240
+const MAX_TOKEN_LIMIT = 10_000_000
+const REASONING_EFFORTS = ['off', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max'] as const
+type ReasoningEffort = typeof REASONING_EFFORTS[number]
+const stringField = (max: number) => z.string().trim().min(1).max(max).refine(value => !/[\r\n\0]/.test(value), 'must not contain a newline or NUL')
+const providerSchema = z.object({ provider: stringField(MAX_IDENTIFIER_LENGTH) }).strict()
+const modelSchema = z.object({
+  id: stringField(MAX_IDENTIFIER_LENGTH),
+  name: stringField(MAX_DISPLAY_NAME_LENGTH).optional(),
+  contextWindow: z.number().int().safe().positive().max(MAX_TOKEN_LIMIT).optional(),
+  maxTokens: z.number().int().safe().positive().max(MAX_TOKEN_LIMIT).optional(),
+  reasoningEfforts: z.array(z.enum(REASONING_EFFORTS)).min(1).refine(
+    efforts => efforts.every((effort, index) => index === 0 || REASONING_EFFORTS.indexOf(efforts[index - 1]!) < REASONING_EFFORTS.indexOf(effort)),
+    'reasoning efforts must be unique and in canonical order',
+  ).optional(),
+}).strict()
+const upsertSchema = z.object({ provider: stringField(MAX_IDENTIFIER_LENGTH), model: modelSchema }).strict()
+
+interface ModelProfile { id: string, name?: string, contextWindow?: number, maxTokens?: number, reasoningEfforts?: ReasoningEffort[] }
+interface EligibleProvider { provider: string, displayName: string, namespace: SettingsNamespaceView, profile: Record<string, unknown> }
+interface CatalogValue { groups: ModelProviderGroup[], failures: Array<{ id: string, name: string, message: string }> }
+
+export const PAIRED_MODEL_CATALOG_PATHS = {
+  catalog: '/api/pair/model-catalog',
+  discover: '/api/pair/model-catalog/discover',
+  upsert: '/api/pair/model-catalog/upsert',
+} as const
+
+export interface PairedModelCatalogDeps {
+  service: PairingService
+  apiProxy: ApiProxy
+  /** The LAN IP literals the host fence accepts, mirroring the /api/pair fence. */
+  lanAddresses: readonly string[]
+}
+
+let rpcSequence = 0
+function request<T>(payload: T): { rpcId: RpcId, payload: T } {
+  rpcSequence += 1
+  return { rpcId: `paired-model-catalog-${Date.now().toString(36)}-${rpcSequence.toString(36)}` as RpcId, payload }
+}
+function isRecord(value: unknown): value is Record<string, unknown> { return typeof value === 'object' && value !== null && !Array.isArray(value) }
+function valueOf<T>(response: RpcResponse<T>): T | undefined { return response.result.ok ? response.result.value : undefined }
+function errorCode(response: RpcResponse<unknown>): string | undefined { return response.result.ok ? undefined : response.result.error.code }
+function reject(res: ServerResponse, status: number, error: string): void { writeJson(res, status, { error }) }
+function publicProviderId(value: string): string {
+  const normalized = value.replace(/[\r\n\0]/g, ' ').trim().slice(0, MAX_IDENTIFIER_LENGTH)
+  return normalized === '' ? 'unknown' : normalized
+}
+
+function publicCatalog(value: CatalogValue): CatalogValue {
+  return {
+    groups: value.groups.map(group => ({ id: group.id, name: group.name, models: group.models.map(model => ({
+      id: model.id, name: model.name,
+      ...model.description === undefined ? {} : { description: model.description },
+      ...model.reasoning === undefined ? {} : { reasoning: model.reasoning },
+    })) })),
+    failures: value.failures.map(failure => ({
+      id: failure.id,
+      name: failure.name,
+      message: `model catalog unavailable for provider ${publicProviderId(failure.id)}`,
+    })),
+  }
+}
+function publicCandidates(models: Array<{ id: string, name?: string, contextWindow?: number, maxTokens?: number }>): unknown[] {
+  return models.map(model => ({ id: model.id,
+    ...model.name === undefined ? {} : { name: model.name },
+    ...model.contextWindow === undefined ? {} : { contextWindow: model.contextWindow },
+    ...model.maxTokens === undefined ? {} : { maxTokens: model.maxTokens },
+  }))
+}
+function fieldsOf(model: ModelProfile, includeId: boolean): Record<string, unknown> {
+  const fields: Record<string, unknown> = {
+    ...includeId ? { id: model.id } : {},
+    ...model.name === undefined ? {} : { name: model.name },
+    ...model.contextWindow === undefined ? {} : { contextWindow: model.contextWindow },
+    ...model.maxTokens === undefined ? {} : { maxTokens: model.maxTokens },
+  }
+  if (model.reasoningEfforts !== undefined) fields.reasoningEfforts = Object.fromEntries(model.reasoningEfforts.map(effort => [effort, effort === 'off' ? null : effort]))
+  return fields
+}
+function groupFor(catalog: CatalogValue, provider: string): ModelProviderGroup | undefined { return catalog.groups.find(group => group.id === provider) }
+async function readCatalog(apiProxy: ApiProxy): Promise<CatalogValue | undefined> {
+  try { return valueOf(await apiProxy.llm.models(request({}))) } catch { return undefined }
+}
+
+/** Resolve one exact active llm-pi-ai provider address, never an input-supplied path. */
+async function eligibleProvider(apiProxy: ApiProxy, requested: string): Promise<{ provider?: EligibleProvider, status?: number, error?: string }> {
+  let providersResponse: Awaited<ReturnType<ApiProxy['llm']['providers']>>
+  let settingsResponse: Awaited<ReturnType<ApiProxy['settings']['describe']>>
+  try {
+    providersResponse = await apiProxy.llm.providers(request({}))
+    settingsResponse = await apiProxy.settings.describe(request({}))
+  } catch { return { status: 502, error: 'model catalog capability is unavailable' } }
+  const providers = valueOf(providersResponse)
+  const settings = valueOf(settingsResponse)
+  if (providers === undefined || settings === undefined) return { status: 502, error: 'model catalog capability is unavailable' }
+  const route = providers.providers.find(candidate => candidate.provider === requested)
+  if (route === undefined) return { status: 404, error: `unknown provider ${requested}` }
+  if (!settings.writable || !route.active || route.settingsNs !== 'llm-pi-ai' || route.settingsPath.length !== 2
+    || route.settingsPath[0] !== 'providers' || route.settingsPath[1] !== requested) return { status: 403, error: `provider ${requested} is not eligible for the paired model catalog` }
+  const namespace = settings.namespaces.find(candidate => candidate.ns === 'llm-pi-ai')
+  const root = namespace !== undefined && isRecord(namespace.value) ? namespace.value : undefined
+  const providersValue = root !== undefined && isRecord(root.providers) ? root.providers : undefined
+  const profile = providersValue !== undefined && isRecord(providersValue[requested]) ? providersValue[requested] : undefined
+  if (namespace === undefined || profile === undefined) return { status: 403, error: `provider ${requested} is not eligible for the paired model catalog` }
+  return { provider: { provider: requested, displayName: route.displayName, namespace, profile } }
+}
+function updatedModels(existing: unknown[], model: ModelProfile): unknown[] {
+  const next = existing.map(entry => isRecord(entry) ? { ...entry } : entry)
+  const index = next.findIndex(entry => isRecord(entry) && entry.id === model.id)
+  const patch = fieldsOf(model, true)
+  if (index >= 0 && isRecord(next[index])) next[index] = { ...next[index], ...patch }
+  else next.push(patch)
+  return next
+}
+function mutationPlan(profile: Record<string, unknown>, provider: string, model: ModelProfile, catalog: CatalogValue): { path: string[], value: unknown } | undefined {
+  if (Array.isArray(profile.models)) return { path: ['providers', provider, 'models'], value: updatedModels(profile.models, model) }
+  const group = groupFor(catalog, provider)
+  if (group?.models.some(entry => entry.id === model.id) === true) {
+    const overrides = isRecord(profile.modelOverrides) ? profile.modelOverrides : undefined
+    const current = overrides?.[model.id]
+    const existing: Record<string, unknown> = isRecord(current) ? current : {}
+    return { path: ['providers', provider, 'modelOverrides', model.id], value: { ...existing, ...fieldsOf(model, false) } }
+  }
+  if (group === undefined || catalog.failures.some(failure => failure.id === provider)) return undefined
+  return { path: ['providers', provider, 'models'], value: [...group.models.map(entry => ({ id: entry.id })), fieldsOf(model, true)] }
+}
+function paired(req: IncomingMessage, service: PairingService): boolean {
+  const deviceId = readCookie(req.headers.cookie, service.config.cookieName)
+  return deviceId !== undefined && service.touchDevice(deviceId)
+}
+async function bodyOf<T>(req: IncomingMessage, schema: z.ZodType<T>): Promise<T | undefined> {
+  try { return schema.parse(await readBoundedJson(req, MAX_BODY_BYTES)) } catch { return undefined }
+}
+
+/** Build the narrow paired-device model catalog routes. */
+export function makePairedModelCatalogRoutes(deps: PairedModelCatalogDeps): WebRoute[] {
+  const { service, apiProxy, lanAddresses } = deps
+  /** Same fence as the /api/pair family: loopback, the advertised LAN literals, or the configured public host. */
+  const fence = (req: IncomingMessage): boolean => {
+    const publicHost = publicHostOf(service.publicBaseUrl)
+    return isTrustedApiRequest(req, publicHost === undefined ? lanAddresses : [...lanAddresses, publicHost])
+  }
+  const gate = (req: IncomingMessage, res: ServerResponse): boolean => {
+    if (!fence(req)) {
+      req.resume()
+      reject(res, 403, 'paired model catalog is not reachable for this origin')
+      return false
+    }
+    if (!paired(req, service)) {
+      req.resume()
+      reject(res, 403, 'paired model catalog requires a live paired device')
+      return false
+    }
+    return true
+  }
+  const catalog = async (req: IncomingMessage, res: ServerResponse): Promise<void> => {
+    if (!gate(req, res)) return
+    if (req.method !== 'GET') return reject(res, 405, 'method not allowed')
+    let providersResponse: Awaited<ReturnType<ApiProxy['llm']['providers']>>
+    let settingsResponse: Awaited<ReturnType<ApiProxy['settings']['describe']>>
+    try { providersResponse = await apiProxy.llm.providers(request({})); settingsResponse = await apiProxy.settings.describe(request({})) } catch { return reject(res, 502, 'model catalog capability is unavailable') }
+    const providers = valueOf(providersResponse)
+    const settings = valueOf(settingsResponse)
+    if (providers === undefined || settings === undefined) return reject(res, 502, 'model catalog capability is unavailable')
+    const namespace = settings.namespaces.find(candidate => candidate.ns === 'llm-pi-ai')
+    const providerMap = namespace !== undefined && isRecord(namespace.value) && isRecord(namespace.value.providers) ? namespace.value.providers : undefined
+    const eligible = settings.writable && providerMap !== undefined ? providers.providers.filter(candidate => candidate.active && candidate.settingsNs === 'llm-pi-ai'
+      && candidate.settingsPath.length === 2 && candidate.settingsPath[0] === 'providers' && candidate.settingsPath[1] === candidate.provider && isRecord(providerMap[candidate.provider]))
+      .map(candidate => ({ provider: candidate.provider, displayName: candidate.displayName })) : []
+    writeJson(res, 200, { capability: 'paired-model-catalog', providers: eligible })
+  }
+  const discover = async (req: IncomingMessage, res: ServerResponse): Promise<void> => {
+    if (!gate(req, res)) return
+    if (req.method !== 'POST') return reject(res, 405, 'method not allowed')
+    const body = await bodyOf(req, providerSchema)
+    if (body === undefined) return reject(res, 400, 'invalid model catalog request')
+    const eligible = await eligibleProvider(apiProxy, body.provider)
+    if (eligible.provider === undefined) return reject(res, eligible.status ?? 502, eligible.error ?? 'model catalog capability is unavailable')
+    try {
+      const result = valueOf(await apiProxy.llm.discoverModels(request({ settingsNs: 'llm-pi-ai', provider: eligible.provider.provider })))
+      if (result === undefined) return reject(res, 502, `model discovery failed for provider ${eligible.provider.provider}`)
+      writeJson(res, 200, { models: publicCandidates(result.models) })
+    } catch { reject(res, 502, `model discovery failed for provider ${eligible.provider.provider}`) }
+  }
+  const upsert = async (req: IncomingMessage, res: ServerResponse): Promise<void> => {
+    if (!gate(req, res)) return
+    if (req.method !== 'POST') return reject(res, 405, 'method not allowed')
+    const body = await bodyOf(req, upsertSchema)
+    if (body === undefined) return reject(res, 400, 'invalid model catalog request')
+    const eligible = await eligibleProvider(apiProxy, body.provider)
+    if (eligible.provider === undefined) return reject(res, eligible.status ?? 502, eligible.error ?? 'model catalog capability is unavailable')
+    const before = await readCatalog(apiProxy)
+    if (before === undefined) return reject(res, 502, `model catalog is unavailable for provider ${body.provider}`)
+    const plan = mutationPlan(eligible.provider.profile, body.provider, body.model, before)
+    if (plan === undefined) return reject(res, 502, `model catalog is unavailable for provider ${body.provider}`)
+    let mutation: Awaited<ReturnType<ApiProxy['settings']['mutate']>>
+    try { mutation = await apiProxy.settings.mutate(request({ ns: 'llm-pi-ai', expectedRevision: eligible.provider.namespace.revision, ops: [{ op: 'set', path: plan.path, value: plan.value }] })) } catch { return reject(res, 502, `model update failed for provider ${body.provider}`) }
+    const code = errorCode(mutation)
+    if (code === 'settings-conflict') return reject(res, 409, `model update conflicted for provider ${body.provider}`)
+    if (code === 'settings-rejected') return reject(res, 422, `model update was rejected for provider ${body.provider}`)
+    if (code !== undefined) return reject(res, 502, `model update failed for provider ${body.provider}`)
+    const after = await readCatalog(apiProxy)
+    if (after === undefined) return reject(res, 502, `model catalog is unavailable for provider ${body.provider}`)
+    writeJson(res, 200, publicCatalog(after))
+  }
+  return [
+    { kind: 'exact', path: PAIRED_MODEL_CATALOG_PATHS.catalog, handler: catalog },
+    { kind: 'exact', path: PAIRED_MODEL_CATALOG_PATHS.discover, handler: discover },
+    { kind: 'exact', path: PAIRED_MODEL_CATALOG_PATHS.upsert, handler: upsert },
+  ]
+}

package/src/pairing.ts

@@ -169,10 +169,13 @@ export const defaultClock: PairingClock = {
 }
 
 /**
- * The pairing state machine. All mutations notify state listeners after the
- * commit point that makes them true, and notification dedupes against the
- * last emitted snapshot — time-driven transitions (a device aging offline)
- * surface on the next sweep without any mutation.
+ * The pairing state machine. Structural mutations issue/accept/stop/revoke
+ * and config updates (LAN bases, tunnel, posture) notify state listeners
+ * after the commit point that makes them true, and notification dedupes
+ * against the last emitted snapshot. Presence-only updates (touchDevice /
+ * heartbeat) just mark the store dirty and broadcast on the next sweep,
+ * which also surfaces time-driven transitions (a device aging offline)
+ * without any mutation.
  */
 export class PairingService {
   private readonly tokens = new Map<string, TokenRecord>()
@@ -432,6 +435,12 @@ export class PairingService {
    * The api/gate path: record activity for a device id and report whether
    * the request may proceed. Unknown or revoked ids (including any device
    * after stop() or idle expiry) are refused.
+   *
+   * Presence refreshes are throttled on purpose: every gated request (and
+   * the mobile SSE keepalive) lands here, so a broadcast per call would fan
+   * a full snapshot out to every status stream on the hot path. The refresh
+   * only updates lastSeenAt and marks the store dirty; the snapshot reaches
+   * listeners at the next sweep() (structural changes notify immediately).
    * @param deviceId - the cookie value of the requesting device.
    * @returns true when the device session is live and was refreshed.
    */
@@ -440,7 +449,6 @@ export class PairingService {
     if (session === undefined) return false
     session.lastSeenAt = this.clock.now()
     this.dirty = true
-    this.notify()
     return true
   }
 

package/src/remote-api.ts

@@ -7,8 +7,10 @@
  * and no per-plugin pairing consult.
  *
  * Security model:
- * - Every request must carry a live paired-device cookie, enforced before
- *   any bytes are forwarded and before any host call.
+ * - While `requirePairingForLan` is on (default), every request must carry a
+ *   live paired-device cookie, enforced before any bytes are forwarded and
+ *   before any host call. With the policy off, the cookie gate is skipped
+ *   (the loopback-only denials below still apply).
  * - The SDK's loopback-only privileged methods (native dialogs, the settings
  *   plane, credentials — the `PRIVILEGED_METHODS` set of client-connection)
  *   are denied here. The set is pinned by tests/remote-contract.spec.ts.
@@ -31,7 +33,6 @@ import {
   DESKTOP_LAUNCHER_PATH,
   LOOPBACK_ONLY_METHODS,
   PLUGIN_MANAGER_PATH,
-  REMOTE_API_PATHS,
   REMOTE_PREFIX,
   REMOTE_UPGRADE_PATHS,
   WEB_UI_SETTINGS_BRIDGE_PATH,
@@ -68,6 +69,13 @@ export interface RemoteApiDeps {
   service: PairingService
   /** The local webServer port the loopback proxy connects to. */
   port: number
+  /**
+   * Live policy: whether the paired-device cookie gates the /remote channel.
+   * When false, requests are proxied without a cookie (the loopback-only
+   * denials still apply). A function is re-read per request, so a settings
+   * edit takes effect without a restart. Defaults to true.
+   */
+  requirePairingForLan?: boolean | (() => boolean)
 }
 
 /** One SDK-shaped error envelope (keeps the desktop client's parse path intact). */
@@ -125,20 +133,25 @@ export function loopbackOnlyDenial(innerPath: string): string | undefined {
 
 /**
  * Build the remote desktop channel HTTP routes.
- * @param deps - pairing service + local port.
+ * @param deps - pairing service + local port + live pairing policy.
  * @returns the routes to register on webServer.
  */
 export function makeRemoteApiRoutes(deps: RemoteApiDeps): WebRoute[] {
-  const { service, port } = deps
+  const { service, port, requirePairingForLan = true } = deps
 
   const handler = (req: IncomingMessage, res: ServerResponse): void => {
     // Cookie gate first — same order as /m/api. Do not buffer an unpaired body.
-    const deviceId = readCookie(req.headers.cookie, service.config.cookieName)
-    const paired = deviceId !== undefined && service.touchDevice(deviceId)
-    if (!paired) {
-      req.resume()
-      envelopeError(res, 403, 'invalid-request', 'unpaired', 'this device is not paired with the desktop')
-      return
+    // With the live policy off, untrusted-but-policy-open callers are proxied
+    // (a stale client rewrite must not 403); loopback-only denials stay below.
+    const require = typeof requirePairingForLan === 'function' ? requirePairingForLan() : requirePairingForLan
+    if (require) {
+      const deviceId = readCookie(req.headers.cookie, service.config.cookieName)
+      const paired = deviceId !== undefined && service.touchDevice(deviceId)
+      if (!paired) {
+        req.resume()
+        envelopeError(res, 403, 'invalid-request', 'unpaired', 'this device is not paired with the desktop')
+        return
+      }
     }
 
     const method = req.method ?? 'GET'
@@ -187,18 +200,21 @@ export function upgradeInnerPath(reqUrl: string | undefined, fallbackPath: strin
 /**
  * Build the WebSocket upgrade routes for the event streams and known plugin
  * sockets. webServer matches upgrades by exact path.
- * @param deps - pairing service + local port.
+ * @param deps - pairing service + local port + live pairing policy.
  * @returns the upgrade routes to register on webServer.
  */
 export function makeRemoteApiUpgradeRoutes(deps: RemoteApiDeps): WebUpgradeRoute[] {
-  const { service, port } = deps
+  const { service, port, requirePairingForLan = true } = deps
 
   const handlerFor = (fallbackPath: string) => (req: IncomingMessage, socket: Duplex, head: Buffer): void => {
-    const deviceId = readCookie(req.headers.cookie, service.config.cookieName)
-    if (deviceId === undefined || !service.touchDevice(deviceId)) {
-      socket.write('HTTP/1.1 403 Forbidden\r\nConnection: close\r\n\r\n')
-      socket.destroy()
-      return
+    const require = typeof requirePairingForLan === 'function' ? requirePairingForLan() : requirePairingForLan
+    if (require) {
+      const deviceId = readCookie(req.headers.cookie, service.config.cookieName)
+      if (deviceId === undefined || !service.touchDevice(deviceId)) {
+        socket.write('HTTP/1.1 403 Forbidden\r\nConnection: close\r\n\r\n')
+        socket.destroy()
+        return
+      }
     }
     const inner = upgradeInnerPath(req.url, fallbackPath)
     const denied = loopbackOnlyDenial(inner.split('?')[0] ?? inner)

package/src/remote-channel-boot.ts

@@ -0,0 +1,131 @@
+/**
+ * Parse-time remote-channel boot patch (issue #987): the browser-half patch
+ * (client/remote-channel.ts) installs when this plugin's boot entry runs,
+ * but `dsh-client-connection` boots earlier and opens its event streams
+ * unrewritten — on a non-loopback origin the SDK fence rejects them and the
+ * workspace list never loads. The host therefore inlines this classic script
+ * right after the opening <head> tag (webserver/index-inject), so the
+ * fetch/WebSocket/EventSource/src rewrite is active before ANY boot entry
+ * executes. The plugin's client apply later adopts the installed seat
+ * (hooks + pending unpaired signal) instead of patching twice.
+ *
+ * The rewrite decisions are generated from REMOTE_CHANNEL_RULES, the same
+ * data the browser patch consumes — the two cannot drift apart. The script
+ * self-skips on loopback origins and never throws.
+ * @module @linxin666/dsh-remote-web-ui/remote-channel-boot
+ */
+
+import { REMOTE_CHANNEL_BOOT_GLOBAL, REMOTE_CHANNEL_RULES, type RemoteChannelRules } from './remote-channel-rules.ts'
+
+/**
+ * Build the inline boot script. The result contains no `</script` sequence
+ * (the injection contract) and installs a {@link RemoteChannelBootSeat} on
+ * the window global.
+ */
+export function buildRemoteChannelBootScript(rules: RemoteChannelRules = REMOTE_CHANNEL_RULES): string {
+  const json = JSON.stringify(rules)
+  const seat = JSON.stringify(REMOTE_CHANNEL_BOOT_GLOBAL)
+  // Modern syntax is fine: module scripts already gate the GUI to current
+  // browsers. Keep everything inside the IIFE and fail closed.
+  return '(function(){' +
+    'try{' +
+    'var w=window,loc=w.location,h=loc.hostname;' +
+    // Loopback origins keep the original paths (mirrors isLoopbackHostname).
+    "if(h==='localhost'||h==='::1'||/^127(\\.\\d{1,3}){3}$/.test(h))return;" +
+    'var R=' + json + ';' +
+    'function sf(p){' +
+    'if(p.indexOf(R.pairPrefix)===0)return false;' +
+    'if(p.indexOf(R.updatePrefix)===0)return false;' +
+    'if(p===R.desktopLauncherPrefix||p.indexOf(R.desktopLauncherPrefix+"/")===0)return false;' +
+    'if(p===R.settingsBridgePrefix||p.indexOf(R.settingsBridgePrefix+"/")===0)return false;' +
+    'if(p.indexOf(R.apiPrefix)===0)return true;' +
+    'if(p.indexOf(R.sidebarPrefix)===0||p==="/sidebar")return true;' +
+    'if(p.indexOf(R.gitPrefix)===0||p==="/git")return true;' +
+    'if(p.indexOf(R.petPrefix)===0||p==="/pet")return true;' +
+    'return false}' +
+    'function sw(p){return R.wsPaths.indexOf(p)!==-1}' +
+    'function rp(p){return R.remotePrefix+p}' +
+    'function so(u){return u.origin===loc.origin}' +
+    'function rr(raw){var u;try{u=new URL(raw,loc.href)}catch(e){return raw}' +
+    'if(u.origin!==loc.origin)return raw;' +
+    'if(!sf(u.pathname))return raw;' +
+    'u.pathname=rp(u.pathname);' +
+    'if(raw.charAt(0)==="/"&&raw.charAt(1)!=="/")return u.pathname+u.search+u.hash;' +
+    'return u.href}' +
+    // The unpaired code reader mirrors isUnpairedDenied's envelope shapes.
+    'function uc(v){' +
+    'if(typeof v!=="object"||v===null)return undefined;' +
+    'var n=v.result;' +
+    'if(typeof n==="object"&&n!==null){' +
+    'var e=n.error;' +
+    'if(typeof e==="object"&&e!==null&&typeof e.code==="string")return e.code}' +
+    'var t=v.error;' +
+    'if(typeof t==="object"&&t!==null&&typeof t.code==="string")return t.code;' +
+    'return undefined}' +
+    'var seat={onUnpaired:null,onPaired:null,pendingUnpaired:false,restore:function(){}};' +
+    'function denied(res){' +
+    'if(res.status!==403)return false;' +
+    'return res.clone().json().then(function(b){return uc(b)==="unpaired"}).catch(function(){return false})}' +
+    'function signal(unpaired){' +
+    'if(unpaired){' +
+    'if(seat.onUnpaired)seat.onUnpaired();else seat.pendingUnpaired=true' +
+    '}else{' +
+    'seat.pendingUnpaired=false;' +
+    'if(seat.onPaired)seat.onPaired()}}' +
+    'var of=w.fetch;' +
+    'w.fetch=function(input,init){' +
+    'var raw=typeof input==="string"||input instanceof URL?input.toString():input.url;' +
+    'var url=new URL(raw,loc.href);' +
+    'if(so(url)&&sf(url.pathname)){' +
+    'var next=new URL(url);' +
+    'next.pathname=rp(url.pathname);' +
+    'var target=typeof input==="string"||input instanceof URL?next.toString():new Request(next,input);' +
+    'return Promise.resolve(of.call(w,target,init)).then(function(res){' +
+    // denied() is sync-false for non-403 and a promise otherwise.
+    'void Promise.resolve(denied(res)).then(signal);' +
+    'return res})}' +
+    'return of.call(w,input,init)};' +
+    'var OW=w.WebSocket;' +
+    'w.WebSocket=function(url,protocols){' +
+    'var p=new URL(url.toString(),loc.href);' +
+    'var o=p.protocol==="wss:"?"https://"+p.host:p.protocol==="ws:"?"http://"+p.host:"";' +
+    'if(o!==""&&o===loc.origin&&sw(p.pathname)){' +
+    'var nx=new URL(p);' +
+    'nx.pathname=rp(p.pathname);' +
+    'return protocols!==undefined?new OW(nx,protocols):new OW(nx)}' +
+    'return protocols!==undefined?new OW(url,protocols):new OW(url)};' +
+    'w.WebSocket.prototype=OW.prototype;' +
+    'w.WebSocket.CONNECTING=OW.CONNECTING;w.WebSocket.OPEN=OW.OPEN;w.WebSocket.CLOSING=OW.CLOSING;w.WebSocket.CLOSED=OW.CLOSED;' +
+    'var OE=w.EventSource;' +
+    'if(OE!==undefined){' +
+    'w.EventSource=function(url,cfg){' +
+    'var p=new URL(url.toString(),loc.href);' +
+    'if(so(p)&&sf(p.pathname)){' +
+    'var nx=new URL(p);' +
+    'nx.pathname=rp(p.pathname);' +
+    'return new OE(nx,cfg)}' +
+    'return new OE(url,cfg)};' +
+    'w.EventSource.prototype=OE.prototype}' +
+    // Resource src accessors (img/script/iframe), mirroring patchSrcAccessor.
+    'var restores=[];' +
+    'function patchSrc(C){' +
+    'if(C===undefined)return;' +
+    'var d=Object.getOwnPropertyDescriptor(C.prototype,"src");' +
+    'if(d===undefined||d.configurable===false||d.set===undefined)return;' +
+    'var os=d.set;' +
+    'Object.defineProperty(C.prototype,"src",{configurable:true,enumerable:d.enumerable!==false,get:d.get,set:function(v){os.call(this,rr(String(v)))}});' +
+    'restores.push(function(){Object.defineProperty(C.prototype,"src",d)})}' +
+    'patchSrc(w.HTMLImageElement);patchSrc(w.HTMLScriptElement);patchSrc(w.HTMLIFrameElement);' +
+    'seat.restore=function(){' +
+    'w.fetch=of;' +
+    'w.WebSocket=OW;' +
+    'if(OE!==undefined)w.EventSource=OE;' +
+    'for(var i=0;i<restores.length;i++)restores[i]();' +
+    'try{delete w[' + seat + ']}catch(e){w[' + seat + ']=undefined}};' +
+    'w[' + seat + ']=seat' +
+    '}catch(e){}' +
+    '})();'
+}
+
+/** The script this plugin contributes; built once from the live rules. */
+export const REMOTE_CHANNEL_BOOT_SCRIPT: string = buildRemoteChannelBootScript()

package/src/remote-channel-rules.ts

@@ -0,0 +1,62 @@
+/**
+ * The remote-channel rewrite contract as pure data (issue #987): both the
+ * browser patch (client/remote-channel.ts) and the parse-time boot patch
+ * (remote-channel-boot.ts, inlined into index.html by the host) decide from
+ * these tables, so the two can never drift apart.
+ * @module @linxin666/dsh-remote-web-ui/remote-channel-rules
+ */
+
+/** The gated mirror prefix (must match src/remote-methods.ts). */
+export const REMOTE_PREFIX = '/remote'
+
+/** Connection-plugin method prefix under the gated channel. */
+export const REMOTE_API_PREFIX = `${REMOTE_PREFIX}/api`
+
+/** Every decision input of the remote-channel rewrite, JSON-serializable. */
+export interface RemoteChannelRules {
+  readonly remotePrefix: string
+  readonly apiPrefix: string
+  readonly pairPrefix: string
+  readonly updatePrefix: string
+  readonly desktopLauncherPrefix: string
+  readonly settingsBridgePrefix: string
+  readonly sidebarPrefix: string
+  readonly gitPrefix: string
+  readonly petPrefix: string
+  readonly wsPaths: readonly string[]
+}
+
+/** The live rule set. */
+export const REMOTE_CHANNEL_RULES: RemoteChannelRules = {
+  remotePrefix: REMOTE_PREFIX,
+  apiPrefix: '/api/',
+  pairPrefix: '/api/pair/',
+  updatePrefix: '/api/update/',
+  desktopLauncherPrefix: '/api/dsh-desktop-launcher',
+  settingsBridgePrefix: '/api/dsh-web-ui-settings',
+  sidebarPrefix: '/sidebar/',
+  gitPrefix: '/git/',
+  petPrefix: '/pet/',
+  wsPaths: [
+    '/api/events.mux',
+    '/api/events.host',
+    '/sidebar/ws/terminal',
+    '/sidebar/ws/agent-terminals',
+    '/api/dsh-ssh/terminal',
+  ],
+}
+
+/** The window global the boot patch publishes its seat under. */
+export const REMOTE_CHANNEL_BOOT_GLOBAL = '__DSH_REMOTE_CHANNEL_BOOT__'
+
+/**
+ * The seat the parse-time boot patch installs: hook seats the plugin's
+ * client apply adopts, a pending-unpaired flag for signals raised before
+ * adoption, and restore() retiring the patch (also removes the global).
+ */
+export interface RemoteChannelBootSeat {
+  onUnpaired: (() => void) | null
+  onPaired: (() => void) | null
+  pendingUnpaired: boolean
+  restore(): void
+}