@linxin666/dsh-remote-web-ui 0.3.23 → 0.4.0

package/src/index.ts

@@ -36,6 +36,7 @@ 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 { withIdentityEncoding } from './http.ts'
 import { TunnelManager, type TunnelInfo } from './tunnel.ts'
 import { PublicBaseKeeper } from './public-base.ts'
 import {
@@ -84,9 +85,12 @@ export const name = 'remote-web-ui'
 export const inject = ['webServer', 'typertGateway', 'connection']
 
 /**
- * Settings namespace of the remote-control capability — the section the web
- * settings surface edits. Spelled here rather than imported: the browser
- * half spells the same value and must not depend on a Host package.
+ * Settings namespace of the remote-control capability. Under the 0.1.7
+ * settings model the namespace IS the Host profile entry id, so this is also
+ * the id the browser half asks `ctx.configForms` for (the family binder
+ * resolves the same value to the owning entry). Spelled here rather than
+ * imported: the browser half spells the same value and must not depend on a
+ * Host package.
  */
 export const REMOTE_WEB_UI_SETTINGS_NAMESPACE = 'remote-web-ui' as SettingsNamespace
 
@@ -100,22 +104,28 @@ export interface Config {
   maxDevices?: number
   /**
    * Idle sessions older than this (ms) are deleted from memory and disk.
-   * Default is 7 days; a leftover cookie no longer authorizes after expiry.
+   * Default is 30 days; a leftover cookie no longer authorizes after expiry.
    */
   idleExpireMs?: number
   /** Cookie name carrying the paired device id. */
   cookieName?: string
   /**
    * When true (default), a desktop Web GUI opened at a non-loopback origin
-   * rides the gated `/remote/api` channel and must carry a live paired-device
-   * cookie — the QR is the only way into remote desktop, and stop()/revoke()
-   * cut the /remote channel and the pairing cookie off immediately. Scope
+   * rides the gated `/remote/api` channel, whose requests must carry a live
+   * paired-device cookie — the QR is the only way into remote desktop, and
+   * stop()/revoke() cut the channel and the pairing cookie off immediately.
+   * This policy selects the transport; it never loosens the channel, whose
+   * gate is unconditional (issue #1665). Scope
    * note for this cohort: direct /api is governed by the harness fence +
    * browser-auth cookie (the api/gate seam has no emitter on 0.1.2-alpha.2),
    * so a harness browser credential a device has already redeemed is not
    * invalidated by stop() — see the README security model. Set false to keep
    * the desktop on plain `/api` (only useful when that origin is already
-   * trusted for `/api`).
+   * trusted for `/api`). Turning the policy off does NOT open the channel:
+   * the /remote proxy attaches the process's own browser-auth credential only
+   * when the request itself presents a live paired-device credential, so an
+   * unpaired LAN/tunnel caller is forwarded without it and the inner route
+   * answers 401.
    */
   requirePairingForLan?: boolean
   /**
@@ -220,6 +230,13 @@ export const Config: z<Config> = z.object({
 /** Presence sweep cadence (a stale device flips to disconnected within two sweeps). */
 const SWEEP_INTERVAL_MS = 10_000
 
+/**
+ * How long one update-status probe answer is reused. The probe fans out one
+ * registry GET per family package plus a GitHub call, and the sidebar update
+ * entry asks for the status on every GUI page load.
+ */
+const UPDATE_STATUS_TTL_MS = 60_000
+
 /**
  * Fully resolved config: every field non-optional except `publicBaseUrl`,
  * which legitimately resolves to `undefined` when unset (the schema keeps it
@@ -237,9 +254,8 @@ type ResolvedConfig = Required<Omit<Config, 'publicBaseUrl' | 'trustedHosts' | '
 
 /**
  * The single mapping from resolved plugin config to the pairing service
- * config. Both the constructed service and every live settings sync reuse
- * it, so no field can be silently dropped when the web settings surface
- * pushes a new value into the running service.
+ * config. Both the constructed service and every later apply of this row
+ * reuse it, so no field can be silently dropped.
  */
 export function pairingConfigOf(resolved: Pick<
   ResolvedConfig,
@@ -305,30 +321,12 @@ function applyImpl(ctx: Context, config?: Config): void {
     profile: config?.profile ?? process.env.DSH_PROFILE ?? DEFAULTS.profile,
     enabled: config?.enabled ?? DEFAULTS.enabled,
   }
-  // The live source the pairing service and the gate read: the settings
-  // section once the web settings surface is served, the composition entry
-  // otherwise (installSection swaps it when the namespace registers).
-  let current: () => Config = () => config ?? {}
-  const resolve = (): ResolvedConfig => {
-    const value = current()
-    return {
-      tokenTtlMs: value.tokenTtlMs ?? DEFAULTS.tokenTtlMs,
-      offlineAfterMs: value.offlineAfterMs ?? DEFAULTS.offlineAfterMs,
-      maxDevices: value.maxDevices ?? DEFAULTS.maxDevices,
-      idleExpireMs: value.idleExpireMs ?? DEFAULTS.idleExpireMs,
-      cookieName: value.cookieName ?? DEFAULTS.cookieName,
-      requirePairingForLan: value.requirePairingForLan ?? DEFAULTS.requirePairingForLan,
-      publicBaseUrl: value.publicBaseUrl ?? envPublicBase,
-      trustedHosts: value.trustedHosts,
-      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,
-    }
-  }
+  // The effective configuration this activation runs on: under the 0.1.7
+  // settings model the plugin's own Config IS its settings document, so the
+  // Host serves the settings page from this schema and reloads the row after a
+  // save — a live edit re-enters apply() with the new value instead of being
+  // pushed into a running instance.
+  const resolve = (): ResolvedConfig => resolved
   const service = new PairingService(pairingConfigOf(resolved))
 
   // ── auto tunnel ─────────────────────────────────────────────────────────
@@ -442,13 +440,14 @@ function applyImpl(ctx: Context, config?: Config): void {
     service.setLanBases(lanBases)
   }
 
-  // Push a committed settings section into the service and gate. The service
+  // Push the effective configuration into the service and gate. The service
   // config object is read per operation (token mint, touch, sweep), and the
-  // gate re-reads its fence flag per request, so a live edit takes effect
-  // without a restart. When `enabled` turns off, the pairing routes and
-  // sweep timer are dropped and all device/token state is revoked, but the
-  // gate listener stays mounted so a LAN-exposed /api stays behind pairing
-  // (now vetoing every non-loopback request) instead of opening the fence.
+  // gate re-reads its fence flag per request, so a saved edit takes effect
+  // without a restart (the Host reloads this row, and apply re-runs). When
+  // `enabled` is off, the pairing routes and sweep timer are dropped and all
+  // device/token state is revoked, but the gate listener stays mounted so a
+  // LAN-exposed /api stays behind pairing (now vetoing every non-loopback
+  // request) instead of opening the fence.
   let disposeRoutes: (() => void) | undefined
   let disposeSweep: (() => void) | undefined
   // ── remote update ────────────────────────────────────────────────────────
@@ -478,16 +477,32 @@ function applyImpl(ctx: Context, config?: Config): void {
     releaseNotesCache.set(version, { at: Date.now(), notes })
     return notes
   }
-  const updateRoutes = makeUpdateRoutes({
-    // Control endpoints are host-surface only: a LAN/phone origin must never
-    // trigger a real install on this machine.
-    fence: request => isTrustedApiRequest(request, []),
-    check: () => checkUpdates({
+  // The status probe fans out one registry GET per family package (plus a
+  // GitHub release-notes call), and the sidebar update entry asks for it on
+  // every GUI page load — so the answer is memoized briefly and concurrent
+  // callers share one probe. A completed update invalidates it.
+  let updateStatusCache: { at: number; value: Awaited<ReturnType<typeof checkUpdates>> } | undefined
+  let updateStatusInFlight: Promise<Awaited<ReturnType<typeof checkUpdates>>> | undefined
+  const checkStatusCached = (): Promise<Awaited<ReturnType<typeof checkUpdates>>> => {
+    const cached = updateStatusCache
+    if (cached !== undefined && Date.now() - cached.at < UPDATE_STATUS_TTL_MS) return Promise.resolve(cached.value)
+    if (updateStatusInFlight !== undefined) return updateStatusInFlight
+    updateStatusInFlight = checkUpdates({
       anchorManifestPath: resolveAnchorPath(),
       resolve: hostResolve,
       fetchLatest: name => fetchLatestVersion(name, fetch),
       fetchReleaseNotes: fetchReleaseNotesCached,
-    }),
+    }).then((value) => {
+      updateStatusCache = { at: Date.now(), value }
+      return value
+    }).finally(() => { updateStatusInFlight = undefined })
+    return updateStatusInFlight
+  }
+  const updateRoutes = makeUpdateRoutes({
+    // Control endpoints are host-surface only: a LAN/phone origin must never
+    // trigger a real install on this machine.
+    fence: request => isTrustedApiRequest(request, []),
+    check: () => checkStatusCached(),
     run: async (): Promise<UpdateRunResult> => {
       const target = resolveUpdateTarget({ anchorManifestPath: resolveAnchorPath() })
       if ('error' in target) {
@@ -504,7 +519,7 @@ function applyImpl(ctx: Context, config?: Config): void {
       // 11 minimumReleaseAge gate can silently keep the installed versions
       // (same-day releases), which a plain exit-0 check would report as
       // success — the user then restarts and nothing changed.
-      return runUpdateVerified({
+      const result = await runUpdateVerified({
         run: { profileDir: target.profileDir, packages: target.packages },
         check: {
           anchorManifestPath: resolveAnchorPath(),
@@ -513,6 +528,9 @@ function applyImpl(ctx: Context, config?: Config): void {
           fetchReleaseNotes: fetchReleaseNotesCached,
         },
       })
+      // The install moved (or failed) the versions the cached status reported.
+      updateStatusCache = undefined
+      return result
     },
   })
   // LAN-bind facts for the settings card, re-read per request so a hot
@@ -580,10 +598,16 @@ function applyImpl(ctx: Context, config?: Config): void {
     if (appShellCache !== undefined && Date.now() - appShellCache.at < APP_SHELL_TTL_MS) return appShellCache.html
     const cookie = await innerAuth.ready()
     try {
-      const response = await fetch(`http://127.0.0.1:${String(ctx.webServer.port)}/`, {
+      const response = await fetch(`http://127.0.0.1:${String(ctx.webServer.port)}/`, withIdentityEncoding({
         headers: cookie !== undefined ? { cookie } : undefined,
-      })
-      if (!response.ok) return undefined
+      }))
+      if (!response.ok) {
+        // A stale credential (secret rotation, 30-day TTL) must not wedge every
+        // later landing: drop it so the next attempt re-redeems, exactly as the
+        // proxy path does on an upstream 401.
+        if (response.status === 401 || response.status === 403) innerAuth.invalidate()
+        return undefined
+      }
       const html = await response.text()
       appShellCache = { at: Date.now(), html }
       return html
@@ -618,15 +642,15 @@ function applyImpl(ctx: Context, config?: Config): void {
         return list
       },
     }),
-    // The remote desktop channel: policy-gated `/remote` prefix that
-    // re-issues fenced paths to loopback (see remote-api.ts). The live
-    // requirePairingForLan is re-read per request, same as the gate listener
-    // and routes above, so a stale client rewrite on an open-LAN deployment
-    // proxies instead of 403ing.
+    // The remote desktop channel: a paired-credential-gated `/remote` prefix
+    // that re-issues fenced paths to loopback (see remote-api.ts). The gate is
+    // unconditional — requirePairingForLan governs the plain /api surface and
+    // the desktop's client-side rewrite only; it is never an authorization
+    // input here, because this channel attaches the process's own browser
+    // credential to everything it forwards (issue #1665).
     ...makeRemoteApiRoutes({
       service,
       port: ctx.webServer.port,
-      requirePairingForLan: () => resolve().requirePairingForLan,
       auth: innerAuth,
     }),
     ...updateRoutes,
@@ -634,7 +658,6 @@ function applyImpl(ctx: Context, config?: Config): void {
   const upgrades = makeRemoteApiUpgradeRoutes({
     service,
     port: ctx.webServer.port,
-    requirePairingForLan: () => resolve().requirePairingForLan,
     auth: innerAuth,
   })
   const gate = makeGateListener(service, () => resolve().requirePairingForLan, () => resolve().enabled)
@@ -718,6 +741,9 @@ function applyImpl(ctx: Context, config?: Config): void {
     console.warn('remote-web-ui: LAN-exposed bind — pairing gates the /remote channel; direct /api stays under the harness fence + browser auth (stop() does not revoke an already-redeemed browser credential)')
   }
 
+  // Apply the effective configuration to the running surfaces once per
+  // activation: the service tunables, the LAN-bind block/firewall, the tunnel
+  // plan, the pairing routes, the presence sweep, and the posture probe.
   const sync = (): void => {
     const value = resolve()
     service.config = pairingConfigOf(value)
@@ -805,6 +831,10 @@ function applyImpl(ctx: Context, config?: Config): void {
         ? plan.targetUrl
         : { kind: 'quick', targetUrl: plan.targetUrl, originHostHeader })
     } else if (plan.mode === 'named') {
+      // The hostname is fixed and known before the process runs, so publish it
+      // now: a named tunnel that fails to start must not leave the previous
+      // mode's ephemeral host as the QR and fence base.
+      publicBase.markRunning(plan.publicUrl)
       tunnel.start({ kind: 'named', token: plan.token, publicUrl: plan.publicUrl })
     } else {
       tunnel.stop()
@@ -824,7 +854,17 @@ function applyImpl(ctx: Context, config?: Config): void {
       }
     }
     const enabled = value.enabled
-    if (!enabled) service.stop()
+    if (!enabled) {
+      service.stop()
+      // The tunnel branch above follows the plan, not the master switch, so an
+      // explicit "off" must also drop the public ingress it started: otherwise
+      // the cloudflared child keeps a live public URL (and the relay keeps its
+      // stable row) while the panel says remote control is stopped. The relay
+      // row is deliberately kept so re-enabling reuses the same origin.
+      tunnel.stop()
+      disposeRelayRegistrar()
+      publicBase.reset()
+    }
     if (disposeRoutes === undefined && enabled) {
       disposeRoutes = ctx.effect(
         () => {
@@ -877,25 +917,8 @@ function applyImpl(ctx: Context, config?: Config): void {
     table.push({ kind: 'script', placement: 'head', text: REMOTE_CHANNEL_BOOT_SCRIPT })
   }), 'remote-web-ui: remote channel boot patch')
 
-  ctx.inject(['settings'], (settingsCtx) => {
-    try {
-      if (typeof settingsCtx.settings?.installSection === 'function') {
-        settingsCtx.settings.installSection(ctx, REMOTE_WEB_UI_SETTINGS_NAMESPACE, Config, config ?? {}, {
-          setSource: (source) => {
-            current = source
-            sync()
-          },
-          onChange: sync,
-        })
-      } else if (typeof settingsCtx.settings?.register === 'function') {
-        const scope = settingsCtx.settings.register(REMOTE_WEB_UI_SETTINGS_NAMESPACE, Config, { base: config ?? {} })
-        current = () => scope?.get?.() ?? (config ?? {})
-        scope?.watch?.(() => { sync() })
-        sync()
-      }
-    } catch {
-      // Defensive fallback against settings registration differences
-    }
-  })
+  // No settings registration: the Host derives this plugin's settings page
+  // from the exported `Config` schema and reloads the row after a save, so
+  // every write re-enters apply() with the new config (see `resolve`).
   sync()
 }

package/src/inner-auth.ts

@@ -7,8 +7,9 @@
  * therefore redeems its own launch token (the same one-time exchange every
  * paired device's first navigation performs) and attaches the resulting
  * cookie to inner requests. The credential is only ever exercised behind the
- * pairing gate: while requirePairingForLan is on, every proxied call already
- * carried a live paired-device cookie before this module is consulted.
+ * pairing gate: the `/remote` channel always requires a live paired-device
+ * credential before this module is consulted, regardless of the
+ * requirePairingForLan LAN policy (issue #1665).
  */
 
 /** Browser-auth credential the proxy attaches to loopback-bound requests. */

package/src/pair-grant.ts

@@ -0,0 +1,131 @@
+/**
+ * One-time pairing grants for the /pair-app landing.
+ *
+ * The QR entry (`/pair-accept?pair=<token>`) used to hand the freshly minted
+ * device id to the app landing in its own URL (`/pair-app?device=<id>`). A
+ * device id is a live session credential: the channel gate authorizes every
+ * gated request by it and the cookie it mirrors lives a year, so a URL carrying
+ * it leaks that credential into browser history, the address bar, and every log
+ * on the path. The landing is reached with a one-time grant instead — 256 bits
+ * of entropy, a short TTL, and single-consume semantics — and the device id
+ * reaches the client only inside the server-rendered shell (the capture script
+ * the landing patches in).
+ *
+ * Consume semantics follow the reference implementation's one-time host
+ * capability (zcode `packages/server/src/hostCapability.ts`): the record is
+ * deleted on EVERY consume attempt — success, expiry, or replay — so a captured
+ * grant is worthless after its first use and a replayed one can never resolve,
+ * and only a first use inside the TTL yields a device.
+ *
+ * @module @linxin666/dsh-remote-web-ui/pair-grant
+ */
+
+import { randomBytes } from 'node:crypto'
+
+/**
+ * Default grant lifetime. The grant only has to survive one redirect chain
+ * from the accept page to the app landing, tunnel round trips included, so it
+ * is far shorter than the device session it stands in for.
+ */
+export const DEFAULT_PAIR_GRANT_TTL_MS = 60_000
+
+/**
+ * Cap on live grants. The accept page is rate-limited per source, but the
+ * table is still caller-driven, so it stays bounded (oldest evicted first)
+ * exactly like the device table.
+ */
+export const MAX_LIVE_GRANTS = 256
+
+/** Clock/entropy injection for tests. */
+export interface PairGrantStoreOptions {
+  /** Grant lifetime in ms (default {@link DEFAULT_PAIR_GRANT_TTL_MS}). */
+  ttlMs?: number
+  /** Clock seam (default Date.now). */
+  now?: () => number
+  /** Entropy seam (default 32 random bytes, base64url). */
+  createGrant?: () => string
+}
+
+/** One issued grant and its absolute expiry (both non-secret to the issuer). */
+export interface PairGrantRecord {
+  /** The one-time secret carried in the /pair-app URL. */
+  grant: string
+  /** Absolute expiry (ms epoch); a consume past this resolves to nothing. */
+  expiresAt: number
+}
+
+/** The grant table surface the routes consume. */
+export interface PairGrantStore {
+  /** Mint one grant bound to a device session. */
+  issue(deviceId: string): PairGrantRecord
+  /** Redeem a grant once, returning its device id (undefined when unusable). */
+  consume(grant: string | undefined): string | undefined
+  /** Liveness check that does not spend the grant (the fence fallback). */
+  peek(grant: string | undefined): string | undefined
+  /** Live grant count (tests/diagnostics). */
+  readonly size: number
+}
+
+/** One live grant. */
+interface GrantEntry {
+  deviceId: string
+  expiresAt: number
+}
+
+/**
+ * Build the grant table. Pure TypeScript with injected clock/randomness so the
+ * whole one-time semantics are unit-testable without a server.
+ */
+export function createPairGrantStore(options: PairGrantStoreOptions = {}): PairGrantStore {
+  const ttlMs = options.ttlMs ?? DEFAULT_PAIR_GRANT_TTL_MS
+  const now = options.now ?? ((): number => Date.now())
+  const createGrant = options.createGrant ?? ((): string => randomBytes(32).toString('base64url'))
+  const entries = new Map<string, GrantEntry>()
+
+  const purgeExpired = (at: number): void => {
+    for (const [grant, entry] of entries) {
+      if (entry.expiresAt <= at) entries.delete(grant)
+    }
+  }
+
+  return {
+    issue(deviceId: string): PairGrantRecord {
+      const issuedAt = now()
+      purgeExpired(issuedAt)
+      while (entries.size >= MAX_LIVE_GRANTS) {
+        const oldest = entries.keys().next().value
+        if (oldest === undefined) break
+        entries.delete(oldest)
+      }
+      const grant = createGrant()
+      const expiresAt = issuedAt + ttlMs
+      entries.set(grant, { deviceId, expiresAt })
+      return { grant, expiresAt }
+    },
+    consume(grant: string | undefined): string | undefined {
+      if (grant === undefined || grant === '') return undefined
+      const consumedAt = now()
+      const entry = entries.get(grant)
+      // Delete before validating: a replayed grant must never resolve, and an
+      // expired one must not linger in the table.
+      entries.delete(grant)
+      purgeExpired(consumedAt)
+      if (entry === undefined || entry.expiresAt <= consumedAt) return undefined
+      return entry.deviceId
+    },
+    peek(grant: string | undefined): string | undefined {
+      if (grant === undefined || grant === '') return undefined
+      const at = now()
+      const entry = entries.get(grant)
+      if (entry === undefined) return undefined
+      if (entry.expiresAt <= at) {
+        entries.delete(grant)
+        return undefined
+      }
+      return entry.deviceId
+    },
+    get size(): number {
+      return entries.size
+    },
+  }
+}

package/src/pairing.persist.test.ts

@@ -201,4 +201,40 @@ describe('PairingService device persistence', () => {
     const deviceId = result.ok ? result.deviceId : ''
     expect(saved[deviceId]?.userAgent).toBe('Mozilla/5.0 TestPhone')
   })
+
+  it('operator is not left with a revocation that a restart silently undoes', () => {
+    // Given a device store that cannot be written (its parent path is a file)
+    // while a stale, readable store sits beside it.
+    const blocker = join(dir, 'blocker')
+    writeFileSync(blocker, 'not a directory')
+    const file = join(blocker, 'devices.json')
+    const removed: string[] = []
+    const service = new PairingService(
+      { ...BASE_CONFIG, devicesFile: file },
+      makeClock(),
+      { removeFile: (path) => { removed.push(path) } },
+    )
+    // When the operator stops remote access and the write cannot be made durable.
+    service.stop()
+    // Then the stale store is handed to the removal step, so a restart cannot
+    // restore the revoked sessions from disk.
+    expect(removed).toEqual([file])
+  })
+
+  it('operator keeps the device store when a revocation persist succeeds', () => {
+    // Given a writable device store with one paired device.
+    const file = join(dir, 'devices.json')
+    const removed: string[] = []
+    const service = new PairingService(
+      { ...BASE_CONFIG, devicesFile: file },
+      makeClock(),
+      { removeFile: (path) => { removed.push(path) } },
+    )
+    const deviceId = pairDevice(service)
+    // When the device is revoked and the write lands.
+    expect(service.revoke(deviceId)).toBe(true)
+    // Then the store stays (with the row gone) and nothing is removed.
+    expect(removed).toEqual([])
+    expect(JSON.parse(readFileSync(file, 'utf8'))).toEqual({})
+  })
 })