@linxin666/dsh-remote-web-ui 0.1.20 → 0.2.0

package/src/mobile/pairing.ts

@@ -0,0 +1,77 @@
+/** Pairing helpers owned by the standalone /m mobile surface. */
+export type PairFetch = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>
+
+export interface MobilePairInput {
+  token: string
+  workspaceId?: string
+}
+
+export type MobilePairAccept =
+  | { ok: true }
+  | { ok: false; message: string }
+
+export type MobilePairBootstrap =
+  | { kind: 'none' }
+  | { kind: 'accepted'; path: string }
+  | { kind: 'failed'; path: string; message: string }
+
+const MOBILE_ROOT = '/m/'
+
+/** Parse a pairing token or a copied pairing link without following its origin. */
+export function parseMobilePairInput(value: string): MobilePairInput | undefined {
+  const trimmed = value.trim()
+  if (trimmed === '') return undefined
+
+  try {
+    const url = new URL(trimmed)
+    const token = url.searchParams.get('pair')
+    if (token === null || token === '') return undefined
+    const workspaceId = url.searchParams.get('workspace')
+    return {
+      token,
+      ...(workspaceId !== null && workspaceId !== '' ? { workspaceId } : {}),
+    }
+  } catch {
+    return { token: trimmed }
+  }
+}
+
+/** Build the safe, token-free mobile destination after successful pairing. */
+export function mobilePairPath(workspaceId?: string): string {
+  return workspaceId === undefined ? MOBILE_ROOT : MOBILE_ROOT + '?workspace=' + encodeURIComponent(workspaceId)
+}
+
+/** Accept one pairing token on this exact browser or installed-web-app context. */
+export async function acceptMobilePair(token: string, fetcher: PairFetch = fetch): Promise<MobilePairAccept> {
+  try {
+    const response = await fetcher('/api/pair/accept', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ token }),
+    })
+    if (response.ok) return { ok: true }
+    if (response.status === 404) return { ok: false, message: '配对链接无效或已过期。' }
+    if (response.status === 409) return { ok: false, message: '配对链接已被使用。' }
+    return { ok: false, message: '此设备无法使用该配对链接。' }
+  } catch {
+    return { ok: false, message: '无法连接到配对服务。' }
+  }
+}
+
+/** Consume a QR pairing token before the mobile application starts making RPC calls. */
+export async function consumeMobilePairUrl(href: string, fetcher: PairFetch = fetch): Promise<MobilePairBootstrap> {
+  let url: URL
+  try {
+    url = new URL(href)
+  } catch {
+    return { kind: 'none' }
+  }
+
+  const token = url.searchParams.get('pair')
+  if (token === null || token === '') return { kind: 'none' }
+
+  const workspaceId = url.searchParams.get('workspace')
+  const path = mobilePairPath(workspaceId === null || workspaceId === '' ? undefined : workspaceId)
+  const result = await acceptMobilePair(token, fetcher)
+  return result.ok ? { kind: 'accepted', path } : { kind: 'failed', path, message: result.message }
+}

package/src/mobile/views/App.test.tsx

@@ -0,0 +1,62 @@
+// @vitest-environment jsdom
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { cleanup, render, screen, waitFor } from '@testing-library/react'
+import { RpcTransportError } from '../rpc.ts'
+
+const api = vi.hoisted(() => ({
+  fetchMobilePreferences: vi.fn(),
+  history: vi.fn(),
+  listSessions: vi.fn(),
+  listWorkspaces: vi.fn(),
+  prompt: vi.fn(),
+}))
+
+vi.mock('../api.ts', () => api)
+vi.mock('../mux.ts', () => ({
+  MuxClient: class {
+    start(): void {}
+    stop(): void {}
+    observe(): void {}
+  },
+}))
+vi.mock('./WorkspaceView.tsx', () => ({ WorkspaceView: () => <div>workspace-ready</div> }))
+vi.mock('./SessionListView.tsx', () => ({ SessionListView: () => <div>sessions-ready</div> }))
+vi.mock('./ChatView.tsx', () => ({ ChatView: () => <div>chat-ready</div> }))
+
+import { App, mobilePairStateForError } from './App.tsx'
+
+afterEach(() => {
+  cleanup()
+  vi.clearAllMocks()
+})
+
+describe('mobile paired-device gate', () => {
+  it('distinguishes a missing paired cookie from a transport outage', () => {
+    expect(mobilePairStateForError(new RpcTransportError('HTTP 403'))).toBe('unpaired')
+    expect(mobilePairStateForError(new RpcTransportError('HTTP 503'))).toBe('unavailable')
+    expect(mobilePairStateForError(new Error('offline'))).toBe('unavailable')
+  })
+
+  it('keeps a valid paired context usable after a failed QR token', async () => {
+    api.fetchMobilePreferences.mockResolvedValue({ mobileEnterToSend: true })
+    render(<App initialPairError="配对链接已被使用。" />)
+
+    await waitFor(() => expect(screen.getByText('workspace-ready')).toBeDefined())
+    expect(screen.queryByRole('alert')).toBeNull()
+  })
+
+  it('shows the pairing screen only when the mobile gateway rejects the device', async () => {
+    api.fetchMobilePreferences.mockRejectedValue(new RpcTransportError('HTTP 403'))
+    render(<App initialPairError="配对链接已被使用。" />)
+
+    await waitFor(() => expect(screen.getByRole('alert').textContent).toContain('配对链接已被使用。'))
+  })
+
+  it('shows a retryable connection failure rather than mounting remote views on outage', async () => {
+    api.fetchMobilePreferences.mockRejectedValue(new RpcTransportError('HTTP 503'))
+    render(<App />)
+
+    await waitFor(() => expect(screen.getByRole('alert').textContent).toContain('无法连接到运行中的 DSH host。'))
+    expect(screen.queryByText('workspace-ready')).toBeNull()
+  })
+})

package/src/mobile/views/App.tsx

@@ -7,12 +7,13 @@
 
 import { useCallback, useEffect, useRef, useState } from 'react'
 import type { WorkspaceView as WorkspaceRow } from '@deepseek-ai/dsh-host-apiproxy/api/workspace'
-import { history as fetchHistory, listSessions, listWorkspaces, prompt } from '../api.ts'
+import { fetchMobilePreferences, history as fetchHistory, listSessions, listWorkspaces, prompt } from '../api.ts'
 import { MuxClient } from '../mux.ts'
 import { RpcCallError, RpcTransportError } from '../rpc.ts'
 import { ChatView } from './ChatView.tsx'
 import { SessionListView } from './SessionListView.tsx'
 import { WorkspaceView as WorkspaceRoster } from './WorkspaceView.tsx'
+import { PairRequiredView } from '../PairRequiredView.tsx'
 
 /** One navigation level. */
 type Route =
@@ -71,11 +72,57 @@ export function formatTime(epochMs: number): string {
   return `${String(date.getMonth() + 1)}月${String(date.getDate())}日 ${clock}`
 }
 
-/**
- * The surface root.
- * @returns the app tree.
- */
-export function App() {
+/** Props accepted by the mobile root before it begins paired-device RPC calls. */
+export interface AppProps {
+  initialPairError?: string
+}
+
+/** Whether the mobile gateway rejected this browser for lack of a paired cookie. */
+export function isUnpairedMobileError(error: unknown): boolean {
+  return error instanceof RpcTransportError && error.message === 'HTTP 403'
+}
+
+/** The result of probing the paired-device-only mobile preference endpoint. */
+export type MobilePairState = 'checking' | 'paired' | 'unpaired' | 'unavailable'
+
+/** Classify an initial mobile preference failure without treating outage as authorization. */
+export function mobilePairStateForError(error: unknown): Extract<MobilePairState, 'unpaired' | 'unavailable'> {
+  return isUnpairedMobileError(error) ? 'unpaired' : 'unavailable'
+}
+
+/** Gate the independent mobile bundle until its own browser context is paired. */
+export function App({ initialPairError }: AppProps) {
+  const [pairState, setPairState] = useState<MobilePairState>('checking')
+
+  useEffect(() => {
+    let current = true
+    void fetchMobilePreferences().then(
+      () => { if (current) setPairState('paired') },
+      (error: unknown) => { if (current) setPairState(mobilePairStateForError(error)) },
+    )
+    return () => { current = false }
+  }, [])
+
+  if (pairState === 'checking') {
+    return <main className="mobile mobile-empty"><p className="mobile-muted">正在连接...</p></main>
+  }
+  if (pairState === 'unpaired') {
+    return <PairRequiredView initialError={initialPairError} onPaired={(path) => { window.location.replace(path) }} />
+  }
+  if (pairState === 'unavailable') {
+    return (
+      <main className="mobile mobile-empty">
+        <p className="mobile-error" role="alert">无法连接到运行中的 DSH host。</p>
+        <button className="mobile-new" type="button" onClick={() => { window.location.reload() }}>重试</button>
+      </main>
+    )
+  }
+
+  return <PairedApp />
+}
+
+/** The existing remote mobile surface, mounted only after device pairing succeeds. */
+function PairedApp() {
   const [route, setRoute] = useState<Route>({ kind: 'workspaces' })
   const [initialWorkspaceId, setInitialWorkspaceId] = useState<string | undefined>(
     () => mobileWorkspaceTarget(window.location.search),

package/src/mobile-pwa.ts

@@ -0,0 +1,19 @@
+/** PWA registration for the standalone /m mobile surface. */
+export const MOBILE_PWA_SCOPE = '/m/'
+export const MOBILE_SERVICE_WORKER_URL = '/m/service-worker.js'
+
+/** Register the mobile shell worker when the current browser supports it. */
+export async function registerMobilePwa(
+  serviceWorker: Pick<ServiceWorkerContainer, 'register'> | undefined = typeof navigator === 'undefined' ? undefined : navigator.serviceWorker,
+): Promise<void> {
+  if (serviceWorker === undefined) return
+
+  try {
+    await serviceWorker.register(MOBILE_SERVICE_WORKER_URL, {
+      scope: MOBILE_PWA_SCOPE,
+      updateViaCache: 'none',
+    })
+  } catch {
+    // HTTP LAN origins cannot register workers; the online mobile UI still works.
+  }
+}

package/src/mobile-routes.ts

@@ -1,11 +1,8 @@
 /**
- * The mobile surface's page routes: `/m` serves the standalone phone UI
- * (an independent bundle, built to lib/mobile.js by the mobile tsdown
- * entry), `/m/mobile.js` serves the bundle itself. The page talks to the
- * host exclusively through the shared /api transport (paired-device cookie
- * already crosses the api/gate fence), so no host-side data plumbing is
- * needed here — only static serving, loopback+paired-fence via the normal
- * webserver route registration.
+ * The mobile surface's page routes: /m canonicalizes to /m/, which serves the
+ * standalone phone UI. The page and worker live in the /m/ scope so the PWA
+ * can cache only its static shell; the paired-device data channel remains at
+ * /m/api and is never handled by the worker.
  */
 
 import { readFile } from 'node:fs/promises'
@@ -14,17 +11,23 @@ import { fileURLToPath } from 'node:url'
 import type { IncomingMessage, ServerResponse } from 'node:http'
 import type { WebRoute } from '@deepseek-ai/dsh-host-webserver'
 
+const MOBILE_ROOT = '/m/'
+const MOBILE_BUNDLE_URL = '/m/mobile.js'
+const MOBILE_MANIFEST_URL = '/m/manifest.webmanifest'
+const MOBILE_WORKER_URL = '/m/service-worker.js'
+const MOBILE_OFFLINE_URL = '/m/offline.html'
+
 /** The standalone mobile bundle (built artifact, next to this file's own lib output). */
 function mobileBundlePath(): string {
   return fileURLToPath(new URL('../lib/mobile.js', import.meta.url))
 }
 
-/** The apple-touch-icon shipped with the package (iOS home-screen icon, 180x180 PNG). */
-function appleTouchIconPath(): string {
-  return fileURLToPath(new URL('../assets/apple-touch-icon.png', import.meta.url))
+/** A package asset available to the host after a registry or git install. */
+function mobileAssetPath(name: string): string {
+  return fileURLToPath(new URL('../assets/' + name, import.meta.url))
 }
 
-/** The mobile page shell: minimal, offline-safe, no external assets. */
+/** The mobile page shell: self-contained, with no document-level user data. */
 function pageHtml(bundleUrl: string): string {
   return [
     '<!doctype html>',
@@ -34,31 +37,78 @@ function pageHtml(bundleUrl: string): string {
     '<meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1, user-scalable=no, viewport-fit=cover">',
     '<meta name="theme-color" content="#f3f5f9">',
     '<meta name="referrer" content="no-referrer">',
-    // iOS "Add to Home Screen" uses apple-touch-icon for the tile icon;
-    // the PNG ships with the package (opaque background — iOS composites
-    // transparency onto black, so the icon avoids transparent regions).
+    '<meta name="mobile-web-app-capable" content="yes">',
+    '<meta name="apple-mobile-web-app-capable" content="yes">',
+    '<meta name="apple-mobile-web-app-title" content="DSH Remote">',
+    '<link rel="manifest" href="/m/manifest.webmanifest">',
     '<link rel="apple-touch-icon" href="/m/apple-touch-icon.png">',
     '<title>移动端远程控制</title>',
     '</head>',
     '<body>',
     '<div id="root"></div>',
-    `<script type="module" src="${bundleUrl}"></script>`,
+    '<script type="module" src="' + bundleUrl + '"></script>',
     '</body>',
     '</html>',
   ].join('')
 }
 
-/** Send a small static body with cache headers (the bundle is content-hashed by rebuild). */
+/** The installable app identity and icon declarations for the /m scope. */
+function manifestJson(): string {
+  return JSON.stringify({
+    id: MOBILE_ROOT,
+    name: 'DSH Remote',
+    short_name: 'DSH Remote',
+    start_url: MOBILE_ROOT,
+    scope: MOBILE_ROOT,
+    display: 'standalone',
+    background_color: '#151424',
+    theme_color: '#f3f5f9',
+    icons: [
+      { src: '/m/icon-192.png', sizes: '192x192', type: 'image/png', purpose: 'any' },
+      { src: '/m/icon-512.png', sizes: '512x512', type: 'image/png', purpose: 'any maskable' },
+    ],
+  }, null, 2)
+}
+
+/** A static fallback that contains no paired-device, session, or workspace data. */
+function offlineHtml(): string {
+  return [
+    '<!doctype html>',
+    '<html lang="zh-CN">',
+    '<head>',
+    '<meta charset="utf-8">',
+    '<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">',
+    '<meta name="theme-color" content="#151424">',
+    '<title>DSH Remote</title>',
+    '<style>body{margin:0;background:#151424;color:#f3f5f9;font:16px system-ui,sans-serif}main{box-sizing:border-box;display:grid;min-height:100vh;place-content:center;padding:32px;text-align:center}h1{margin:0 0 12px;font-size:24px}p{margin:0;color:#c4c7d8;line-height:1.5}</style>',
+    '</head>',
+    '<body><main><h1>DSH Remote</h1><p>Cannot reach the running DSH host. Restore the connection and reopen the app.</p></main></body>',
+    '</html>',
+  ].join('')
+}
+
+/** Send a small static UTF-8 body with revalidation headers. */
 function writeStatic(res: ServerResponse, status: number, type: string, body: string): void {
   res.writeHead(status, {
-    'content-type': `${type}; charset=utf-8`,
+    'content-type': type + '; charset=utf-8',
+    'cache-control': 'no-cache',
+    'referrer-policy': 'no-referrer',
+  })
+  res.end(body)
+}
+
+/** Send the worker with the same scope it registers for, without HTTP caching. */
+function writeServiceWorker(res: ServerResponse, body: string): void {
+  res.writeHead(200, {
+    'content-type': 'text/javascript; charset=utf-8',
     'cache-control': 'no-cache',
     'referrer-policy': 'no-referrer',
+    'service-worker-allowed': MOBILE_ROOT,
   })
   res.end(body)
 }
 
-/** Send the PNG icon as a binary body (unlike text assets, the PNG must not be decoded to utf-8). */
+/** Send a PNG body without decoding it to UTF-8. */
 function writePng(res: ServerResponse, status: number, body: Buffer): void {
   res.writeHead(status, {
     'content-type': 'image/png',
@@ -68,16 +118,34 @@ function writePng(res: ServerResponse, status: number, body: Buffer): void {
   res.end(body)
 }
 
+/** Canonicalize the old /m route while retaining pair and workspace query parameters. */
+function redirectToMobileRoot(req: IncomingMessage, res: ServerResponse): void {
+  const url = new URL(req.url ?? '/m', 'http://x')
+  res.writeHead(308, {
+    location: MOBILE_ROOT + url.search,
+    'cache-control': 'no-store',
+    'referrer-policy': 'no-referrer',
+  })
+  res.end()
+}
+
 /**
  * Build the mobile page routes.
- * @returns the two exact routes to register on webServer.
+ * @returns Exact routes for the canonical page, static shell, and PWA assets.
  */
 export function makeMobileRoutes(): WebRoute[] {
   const handlePage = (_req: IncomingMessage, res: ServerResponse): void => {
-    writeStatic(res, 200, 'text/html', pageHtml('/m/mobile.js'))
+    writeStatic(res, 200, 'text/html', pageHtml(MOBILE_BUNDLE_URL))
+  }
+  const handleManifest = (_req: IncomingMessage, res: ServerResponse): void => {
+    writeStatic(res, 200, 'application/manifest+json', manifestJson())
   }
+  const handleOffline = (_req: IncomingMessage, res: ServerResponse): void => {
+    writeStatic(res, 200, 'text/html', offlineHtml())
+  }
+
   // The bundle is immutable for the process lifetime (a rebuild requires a
-  // host restart), so the ~456KB body is read from disk once, not per phone.
+  // host restart), so the body is read from disk once, not per phone.
   let bundleBody: string | undefined
   const handleBundle = async (_req: IncomingMessage, res: ServerResponse): Promise<void> => {
     if (bundleBody === undefined) {
@@ -95,22 +163,47 @@ export function makeMobileRoutes(): WebRoute[] {
     }
     writeStatic(res, 200, 'text/javascript', bundleBody)
   }
-  const handleIcon = async (_req: IncomingMessage, res: ServerResponse): Promise<void> => {
-    const path = appleTouchIconPath()
+
+  let workerBody: string | undefined
+  const handleWorker = async (_req: IncomingMessage, res: ServerResponse): Promise<void> => {
+    if (workerBody === undefined) {
+      const path = mobileAssetPath('mobile-service-worker.js')
+      if (!existsSync(path)) {
+        writeStatic(res, 503, 'text/plain', 'mobile service worker not found')
+        return
+      }
+      try {
+        workerBody = await readFile(path, 'utf8')
+      } catch {
+        writeStatic(res, 500, 'text/plain', 'failed to read the mobile service worker')
+        return
+      }
+    }
+    writeServiceWorker(res, workerBody)
+  }
+
+  const makeIconHandler = (asset: string): WebRoute['handler'] => async (_req, res) => {
+    const path = mobileAssetPath(asset)
     if (!existsSync(path)) {
-      writeStatic(res, 404, 'text/plain', 'apple-touch-icon not found')
+      writeStatic(res, 404, 'text/plain', asset + ' not found')
       return
     }
     try {
-      const body = await readFile(path)
-      writePng(res, 200, body)
+      writePng(res, 200, await readFile(path))
     } catch {
-      writeStatic(res, 500, 'text/plain', 'failed to read the apple-touch-icon')
+      writeStatic(res, 500, 'text/plain', 'failed to read ' + asset)
     }
   }
+
   return [
-    { kind: 'exact', path: '/m', handler: handlePage },
-    { kind: 'exact', path: '/m/mobile.js', handler: handleBundle },
-    { kind: 'exact', path: '/m/apple-touch-icon.png', handler: handleIcon },
+    { kind: 'exact', path: '/m', handler: redirectToMobileRoot },
+    { kind: 'exact', path: MOBILE_ROOT, handler: handlePage },
+    { kind: 'exact', path: MOBILE_BUNDLE_URL, handler: handleBundle },
+    { kind: 'exact', path: MOBILE_MANIFEST_URL, handler: handleManifest },
+    { kind: 'exact', path: MOBILE_WORKER_URL, handler: handleWorker },
+    { kind: 'exact', path: MOBILE_OFFLINE_URL, handler: handleOffline },
+    { kind: 'exact', path: '/m/apple-touch-icon.png', handler: makeIconHandler('apple-touch-icon.png') },
+    { kind: 'exact', path: '/m/icon-192.png', handler: makeIconHandler('mobile-icon-192.png') },
+    { kind: 'exact', path: '/m/icon-512.png', handler: makeIconHandler('mobile-icon-512.png') },
   ]
 }

package/src/pairing-access.ts

@@ -0,0 +1,36 @@
+/**
+ * Optional cordis service other host plugins can ctx.get without taking a
+ * package dependency: a live paired-device cookie is an allow path on
+ * routes that sit outside /api (and therefore outside api/gate).
+ */
+import type { IncomingMessage } from 'node:http'
+import { Service, type Context } from '@deepseek-ai/cordis'
+
+/** Named lookup key sibling plugins pass to ctx.get. */
+export const REMOTE_WEB_UI_PAIRING = 'remoteWebUiPairing'
+
+/**
+ * Pairing identity for one HTTP request. Structural: consumers must not
+ * import this class, only the method shape.
+ */
+export class RemoteWebUiPairing extends Service {
+  /**
+   * @param ctx - host plugin context.
+   * @param check - live cookie + session predicate (re-read per request).
+   */
+  constructor(
+    ctx: Context,
+    private readonly check: (request: IncomingMessage) => boolean,
+  ) {
+    super(ctx, REMOTE_WEB_UI_PAIRING)
+  }
+
+  /**
+   * Whether the request carries a live paired-device cookie.
+   * @param request - the incoming HTTP request.
+   * @returns true when the session is live and was refreshed.
+   */
+  isPairedDevice(request: IncomingMessage): boolean {
+    return this.check(request)
+  }
+}

package/src/pairing.persist.test.ts

@@ -0,0 +1,145 @@
+/**
+ * PairingService device-session persistence: with `devicesFile` set, sessions
+ * written on accept/stop survive a process restart (a new PairingService
+ * instance), so a previously paired phone — whose cookie already lives 365
+ * days — never needs to re-scan the QR after `dsh web` restarts.
+ */
+import { mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { pairingConfigOf } from './index.ts'
+import { PairingService, type PairingClock, type PairingConfig } from './pairing.ts'
+
+const BASE_CONFIG: Omit<PairingConfig, 'devicesFile'> = {
+  tokenTtlMs: 60_000,
+  offlineAfterMs: 25_000,
+  maxDevices: 4,
+  cookieName: 'dsh_pair',
+}
+
+/** Deterministic clock: tokens are issued in a fixed, readable sequence. */
+function makeClock(): PairingClock {
+  let n = 0
+  return {
+    now: () => 1_000_000 + n,
+    randomToken: () => `tok${(n++).toString().padStart(6, '0')}`,
+  }
+}
+
+/** Pair a device on a service: issue a token and immediately accept it. */
+function pairDevice(service: PairingService): string {
+  service.setPublicBaseUrl('https://pairing.example.trycloudflare.com')
+  const { token } = service.issue()
+  const result = service.accept(token)
+  if (!result.ok) throw new Error(`pair failed: ${result.code}`)
+  return result.deviceId
+}
+
+describe('PairingService device persistence', () => {
+  let dir: string
+
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), 'remote-web-ui-persist-'))
+  })
+
+  afterEach(() => {
+    rmSync(dir, { recursive: true, force: true })
+  })
+
+  it('restores paired sessions across a process restart', () => {
+    const file = join(dir, 'devices.json')
+    const first = new PairingService({ ...BASE_CONFIG, devicesFile: file }, makeClock())
+    const deviceId = pairDevice(first)
+    expect(readFileSync(file, 'utf8')).toContain(deviceId)
+    // Device ids are session credentials: the persisted file is 0600.
+    expect(statSync(file).mode & 0o777).toBe(0o600)
+
+    // Simulated restart: a brand-new service instance reading the same file.
+    const second = new PairingService({ ...BASE_CONFIG, devicesFile: file }, makeClock())
+    expect(second.hasDevice(deviceId)).toBe(true)
+  })
+
+  it('carries devicesFile through the config mapping used by sync() (regression)', () => {
+    const file = join(dir, 'devices.json')
+    const mapped = pairingConfigOf({
+      tokenTtlMs: 60_000,
+      offlineAfterMs: 25_000,
+      maxDevices: 4,
+      cookieName: 'dsh_pair',
+      devicesFile: file,
+    })
+    expect(mapped.devicesFile).toBe(file)
+  })
+
+  it('keeps persisting after a sync-style service.config rebuild', () => {
+    const file = join(dir, 'devices.json')
+    const service = new PairingService({ ...BASE_CONFIG, devicesFile: file }, makeClock())
+    // applyImpl/sync() reassigns service.config from the resolved config on
+    // mount and on every settings change; the rebuild must not drop devicesFile.
+    service.config = pairingConfigOf({
+      tokenTtlMs: 60_000,
+      offlineAfterMs: 25_000,
+      maxDevices: 4,
+      cookieName: 'dsh_pair',
+      devicesFile: file,
+    })
+    const deviceId = pairDevice(service)
+    const restarted = new PairingService({ ...BASE_CONFIG, devicesFile: file }, makeClock())
+    expect(restarted.hasDevice(deviceId)).toBe(true)
+  })
+
+  it('clamps a persisted table to maxDevices when the file holds more sessions', () => {
+    const file = join(dir, 'devices.json')
+    writeFileSync(file, JSON.stringify({
+      dev1: { createdAt: 1_000, lastSeenAt: 1_000 },
+      dev2: { createdAt: 2_000, lastSeenAt: 2_000 },
+      dev3: { createdAt: 3_000, lastSeenAt: 3_000 },
+    }))
+    const service = new PairingService({ ...BASE_CONFIG, maxDevices: 2, devicesFile: file }, makeClock())
+    expect(service.hasDevice('dev3')).toBe(true)
+    expect(service.hasDevice('dev2')).toBe(true)
+    expect(service.hasDevice('dev1')).toBe(false)
+  })
+
+  it('keeps sessions memory-only when devicesFile is unset', () => {
+    const first = new PairingService({ ...BASE_CONFIG }, makeClock())
+    const deviceId = pairDevice(first)
+    // No file was written; a fresh instance without the option knows nothing.
+    const second = new PairingService({ ...BASE_CONFIG }, makeClock())
+    expect(second.hasDevice(deviceId)).toBe(false)
+  })
+
+  it('persists revocation by stop() across a restart', () => {
+    const file = join(dir, 'devices.json')
+    const first = new PairingService({ ...BASE_CONFIG, devicesFile: file }, makeClock())
+    const deviceId = pairDevice(first)
+    first.stop()
+
+    const second = new PairingService({ ...BASE_CONFIG, devicesFile: file }, makeClock())
+    expect(second.hasDevice(deviceId)).toBe(false)
+  })
+
+  it('persists FIFO eviction when the device cap is reached', () => {
+    const file = join(dir, 'devices.json')
+    const first = new PairingService({ ...BASE_CONFIG, maxDevices: 2, devicesFile: file }, makeClock())
+    const firstDevice = pairDevice(first)
+    const secondDevice = pairDevice(first)
+    const thirdDevice = pairDevice(first) // evicts firstDevice
+    expect(first.hasDevice(firstDevice)).toBe(false)
+
+    const second = new PairingService({ ...BASE_CONFIG, maxDevices: 2, devicesFile: file }, makeClock())
+    expect(second.hasDevice(secondDevice)).toBe(true)
+    expect(second.hasDevice(thirdDevice)).toBe(true)
+    expect(second.hasDevice(firstDevice)).toBe(false)
+  })
+
+  it('tolerates a corrupt or missing file instead of refusing to boot', () => {
+    const file = join(dir, 'devices.json')
+    writeFileSync(file, '{ this is not json !!!')
+    expect(() => new PairingService({ ...BASE_CONFIG, devicesFile: file }, makeClock())).not.toThrow()
+
+    const ghost = join(dir, 'does-not-exist.json')
+    expect(() => new PairingService({ ...BASE_CONFIG, devicesFile: ghost }, makeClock())).not.toThrow()
+  })
+})