dsh-plugin-mobile-gateway 0.1.17 → 0.3.0

package/lib/client.js

@@ -0,0 +1,423 @@
+// Browser half of dsh-plugin-mobile-gateway. The package manifest makes this
+// bundle part of DSH's client-module graph; it contributes one sidebar footer
+// action and one shell overlay without replacing shipped UI seats.
+window.__ModuleLoader__.load({
+  id: 'dsh-plugin-mobile-gateway',
+  factory: (require) => {
+    const React = require('react')
+    const module = { exports: {} }
+    const exports = module.exports
+
+    let open = false
+    const listeners = new Set()
+    const setOpen = (value) => {
+      open = value
+      for (const listener of listeners) listener()
+    }
+    const subscribe = (listener) => {
+      listeners.add(listener)
+      return () => listeners.delete(listener)
+    }
+    const getOpen = () => open
+
+    const colors = {
+      panel: 'var(--color-bg, #111318)',
+      card: 'var(--color-bg-elevated, rgba(127,127,127,.08))',
+      text: 'var(--color-text, #f4f4f5)',
+      muted: 'var(--color-text-muted, #9297a2)',
+      border: 'var(--color-border, rgba(127,127,127,.24))',
+      accent: 'var(--color-primary, #4f7cff)',
+      danger: '#dc4c64',
+      success: '#2fb171',
+    }
+    const styles = {
+      backdrop: {
+        position: 'fixed', inset: 0, zIndex: 1200, pointerEvents: 'auto',
+        background: 'rgba(0,0,0,.32)', display: 'flex', justifyContent: 'flex-end',
+      },
+      panel: {
+        width: 380, maxWidth: 'calc(100vw - 24px)', height: '100%', overflowY: 'auto',
+        background: colors.panel, color: colors.text, borderLeft: `1px solid ${colors.border}`,
+        boxShadow: '-12px 0 40px rgba(0,0,0,.22)', padding: 20,
+        fontFamily: 'system-ui, sans-serif', fontSize: 13, boxSizing: 'border-box',
+      },
+      header: { display: 'flex', justifyContent: 'space-between', alignItems: 'center', marginBottom: 18 },
+      title: { margin: 0, fontSize: 18, fontWeight: 650 },
+      card: { background: colors.card, border: `1px solid ${colors.border}`, borderRadius: 12, padding: 14, marginBottom: 12 },
+      label: { display: 'block', color: colors.muted, fontSize: 12, marginBottom: 6 },
+      input: { width: '100%', boxSizing: 'border-box', border: `1px solid ${colors.border}`, borderRadius: 8, padding: '8px 10px', marginBottom: 10, background: 'transparent', color: 'inherit', outline: 'none' },
+      pairingText: { width: '100%', minHeight: 86, boxSizing: 'border-box', resize: 'vertical', border: `1px solid ${colors.border}`, borderRadius: 8, padding: '9px 10px', margin: '10px 0', background: 'transparent', color: 'inherit', outline: 'none', fontFamily: 'ui-monospace, SFMono-Regular, Menlo, monospace', fontSize: 11, lineHeight: 1.45, overflowWrap: 'anywhere' },
+      button: { cursor: 'pointer', border: `1px solid ${colors.border}`, background: 'transparent', borderRadius: 8, padding: '7px 11px', color: 'inherit', font: 'inherit' },
+      primary: { background: colors.accent, color: '#fff', borderColor: colors.accent, width: '100%' },
+      muted: { color: colors.muted, fontSize: 12, lineHeight: 1.55 },
+      row: { display: 'grid', gridTemplateColumns: 'minmax(0, 1fr) auto', columnGap: 12, alignItems: 'center', padding: '12px 0', borderBottom: `1px solid ${colors.border}` },
+      badge: { display: 'inline-flex', alignItems: 'center', gap: 5, fontSize: 11, marginLeft: 8, color: colors.muted },
+      dot: { width: 7, height: 7, borderRadius: 99, display: 'inline-block' },
+      error: { color: '#ff8092', background: 'rgba(220,76,100,.12)', borderRadius: 8, padding: 10, marginBottom: 12 },
+      qr: { display: 'block', width: 220, height: 220, margin: '12px auto', background: '#fff', borderRadius: 10, padding: 8 },
+      switch: { position: 'relative', display: 'inline-flex', width: 42, height: 24, flexShrink: 0 },
+      switchInput: { position: 'absolute', opacity: 0, width: 1, height: 1 },
+      switchTrack: { position: 'absolute', inset: 0, borderRadius: 99, transition: 'background .18s ease', cursor: 'pointer' },
+      switchKnob: { position: 'absolute', top: 3, width: 18, height: 18, borderRadius: 99, background: '#fff', boxShadow: '0 1px 3px rgba(0,0,0,.35)', transition: 'left .18s ease', pointerEvents: 'none' },
+    }
+
+    async function request(path, options) {
+      const response = await fetch(path, { credentials: 'same-origin', ...options })
+      const body = await response.json().catch(() => ({}))
+      if (!response.ok) throw new Error(body.message || body.error || `HTTP ${response.status}`)
+      return body
+    }
+
+    function inferredUrl(wsPath) {
+      const scheme = window.location.protocol === 'https:' ? 'wss:' : 'ws:'
+      return `${scheme}//${window.location.host}${wsPath || '/ws/mobile'}`
+    }
+
+    function DeviceRow({ device, onRevoke, revoking }) {
+      const triggerRevoke = (event) => {
+        event.preventDefault()
+        event.stopPropagation()
+        if (!revoking) onRevoke(device)
+      }
+      return React.createElement('div', { style: styles.row },
+        React.createElement('div', { style: { minWidth: 0, overflow: 'hidden' } },
+          React.createElement('div', { style: { overflow: 'hidden', textOverflow: 'ellipsis', whiteSpace: 'nowrap' } },
+            device.name,
+            React.createElement('span', { style: styles.badge },
+              React.createElement('span', { style: { ...styles.dot, background: device.online ? colors.success : colors.muted } }),
+              device.online ? `在线${device.connections > 1 ? ` · ${device.connections} 个连接` : ''}` : '离线')),
+          React.createElement('div', { style: { ...styles.muted, overflow: 'hidden', textOverflow: 'ellipsis', whiteSpace: 'nowrap', marginTop: 3 } },
+            device.lastSeenAt ? `最近连接：${new Date(device.lastSeenAt).toLocaleString()}` : '尚未连接')),
+        React.createElement('button', {
+          type: 'button',
+          disabled: revoking,
+          style: {
+            ...styles.button,
+            color: colors.danger,
+            background: 'transparent',
+            borderColor: 'rgba(220,76,100,.55)',
+            flexShrink: 0,
+            minWidth: 54,
+            opacity: revoking ? .6 : 1,
+          },
+          title: `吊销 ${device.name}`,
+          // Pointer-up is more reliable than click inside the shell overlay on
+          // touch devices. The click handler remains for keyboard activation.
+          onPointerUp: triggerRevoke,
+          onClick: (event) => {
+            if (event.detail === 0) triggerRevoke(event)
+          },
+        }, revoking ? '吊销中…' : '吊销'))
+    }
+
+    function DevicePanel() {
+      const [devices, setDevices] = React.useState(null)
+      const [status, setStatus] = React.useState(null)
+      const [publicUrl, setPublicUrl] = React.useState('')
+      const [deviceName, setDeviceName] = React.useState('iPhone')
+      const [qr, setQr] = React.useState(null)
+      const [error, setError] = React.useState(null)
+      const [busy, setBusy] = React.useState(false)
+      const [refreshing, setRefreshing] = React.useState(false)
+      const [refreshNotice, setRefreshNotice] = React.useState(null)
+      const [pairingTokenCopied, setPairingTokenCopied] = React.useState(false)
+      const [deviceNotice, setDeviceNotice] = React.useState(null)
+      const [deviceNoticeError, setDeviceNoticeError] = React.useState(false)
+      const [revokingIds, setRevokingIds] = React.useState(() => new Set())
+      const revokingIdsRef = React.useRef(new Set())
+
+      const refresh = React.useCallback(async () => {
+        try {
+          const [deviceData, statusData] = await Promise.all([
+            request('/mgw/devices'),
+            request('/mgw/status'),
+          ])
+          const nextDevices = deviceData.devices || []
+          // Keep existing DOM rows alive when polling returns identical data.
+          // Replacing them every three seconds can swallow a pointer/click that
+          // started on the old button and ended after React replaced the row.
+          if (revokingIdsRef.current.size === 0) {
+            setDevices((current) => JSON.stringify(current) === JSON.stringify(nextDevices) ? current : nextDevices)
+          }
+          setStatus((current) => JSON.stringify(current) === JSON.stringify(statusData) ? current : statusData)
+          setPublicUrl((current) => current || statusData.publicUrl || inferredUrl(statusData.wsPath))
+          return true
+        } catch (cause) {
+          setError(cause.message)
+          return false
+        }
+      }, [])
+
+      const manualRefresh = async () => {
+        if (refreshing) return
+        setRefreshing(true)
+        setRefreshNotice(null)
+        const succeeded = await refresh()
+        setRefreshing(false)
+        if (succeeded) {
+          setError(null)
+          setRefreshNotice(`已刷新 · ${new Date().toLocaleTimeString()}`)
+          window.setTimeout(() => setRefreshNotice(null), 2200)
+        }
+      }
+
+      React.useEffect(() => {
+        let active = true
+        refresh()
+        const timer = window.setInterval(refresh, 3000)
+        return () => { active = false; window.clearInterval(timer) }
+      }, [refresh])
+
+      const pair = async () => {
+        setBusy(true)
+        setError(null)
+        setPairingTokenCopied(false)
+        try {
+          const data = await request('/mgw/pair', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ name: deviceName, publicUrl }),
+          })
+          setQr(data)
+        } catch (cause) {
+          setError(cause.message)
+        } finally {
+          setBusy(false)
+        }
+      }
+
+      const copyPairingText = async () => {
+        if (!qr || !qr.qrPayload) return
+        try {
+          if (!navigator.clipboard || typeof navigator.clipboard.writeText !== 'function') {
+            throw new Error('当前浏览器不允许直接写入剪贴板，请选中文本后手动复制')
+          }
+          await navigator.clipboard.writeText(qr.qrPayload)
+          setError(null)
+          setPairingTokenCopied(true)
+          window.setTimeout(() => setPairingTokenCopied(false), 2200)
+        } catch (cause) {
+          setPairingTokenCopied(false)
+          setError(cause.message)
+        }
+      }
+
+      const toggleGateway = async () => {
+        const enabled = !(status && status.gatewayEnabled)
+        setBusy(true)
+        setError(null)
+        try {
+          const data = await request('/mgw/gateway', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ enabled }),
+          })
+          setStatus((current) => ({ ...(current || {}), ...data }))
+          if (!enabled) setQr(null)
+        } catch (cause) {
+          setError(cause.message)
+        } finally {
+          setBusy(false)
+        }
+      }
+
+      const toggleAuth = async () => {
+        const enabled = !(status && status.requireAuth)
+        if (!enabled && !window.confirm('关闭设备鉴权后，任何能访问移动网关的人都可以控制 DSH。此选项仅限 Debug 阶段使用，确定继续吗？')) return
+        setBusy(true)
+        setError(null)
+        try {
+          const data = await request('/mgw/auth', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ enabled }),
+          })
+          setStatus((current) => ({ ...(current || {}), requireAuth: data.requireAuth }))
+        } catch (cause) {
+          setError(cause.message)
+        } finally {
+          setBusy(false)
+        }
+      }
+
+      const revoke = async (device) => {
+        if (revokingIdsRef.current.has(device.id)) return
+        setDeviceNotice(null)
+        setDeviceNoticeError(false)
+        setError(null)
+        revokingIdsRef.current.add(device.id)
+        setRevokingIds((current) => new Set(current).add(device.id))
+        try {
+          await request(`/mgw/devices/${encodeURIComponent(device.id)}/revoke`, { method: 'POST' })
+          setDevices((current) => Array.isArray(current) ? current.filter((item) => item.id !== device.id) : current)
+          setDeviceNotice(`已吊销 ${device.name}`)
+          window.setTimeout(() => setDeviceNotice(null), 2200)
+        } catch (cause) {
+          setDeviceNoticeError(true)
+          setDeviceNotice(`吊销失败：${cause.message}`)
+          setError(cause.message)
+        } finally {
+          revokingIdsRef.current.delete(device.id)
+          setRevokingIds((current) => {
+            const next = new Set(current)
+            next.delete(device.id)
+            return next
+          })
+          await refresh()
+        }
+      }
+
+      return React.createElement('div', { style: styles.backdrop, onMouseDown: () => setOpen(false) },
+        React.createElement('aside', { style: styles.panel, onMouseDown: (event) => event.stopPropagation(), role: 'dialog', 'aria-modal': true, 'aria-label': '移动设备管理' },
+          React.createElement('div', { style: styles.header },
+            React.createElement('div', null,
+              React.createElement('h2', { style: styles.title }, '移动设备'),
+              React.createElement('div', { style: styles.muted }, status && status.gatewayEnabled ? '移动网关已开启 · 设备鉴权生效中' : '移动网关已关闭 · 普通 WebUI 模式')),
+            React.createElement('button', { style: styles.button, onClick: () => setOpen(false), 'aria-label': '关闭' }, '✕')),
+          error ? React.createElement('div', { style: styles.error }, error) : null,
+          React.createElement('section', { style: styles.card },
+            React.createElement('div', { style: { display: 'flex', justifyContent: 'space-between', gap: 14, alignItems: 'center' } },
+              React.createElement('div', null,
+                React.createElement('strong', null, '允许移动设备连接'),
+                React.createElement('div', { style: { ...styles.muted, marginTop: 4 } }, status && status.gatewayEnabled
+                  ? status.connectedClients > 0
+                    ? `${status.connectedClients} 个连接，网关保持开启`
+                    : `等待可信设备连接${status.waitExpiresAt ? `，约 ${Math.max(1, Math.ceil((status.waitExpiresAt - Date.now()) / 60000))} 分钟后自动关闭` : ''}`
+                  : '关闭时不会接受移动设备连接')),
+              React.createElement('label', { style: { ...styles.switch, opacity: busy || !status ? .55 : 1 }, title: status && status.gatewayEnabled ? '关闭移动网关' : '开启移动网关' },
+                React.createElement('input', {
+                  type: 'checkbox',
+                  role: 'switch',
+                  'aria-label': '允许移动设备连接',
+                  'aria-checked': !!(status && status.gatewayEnabled),
+                  checked: !!(status && status.gatewayEnabled),
+                  disabled: busy || !status,
+                  onChange: toggleGateway,
+                  style: styles.switchInput,
+                }),
+                React.createElement('span', { style: { ...styles.switchTrack, background: status && status.gatewayEnabled ? colors.success : colors.muted } }),
+                React.createElement('span', { style: { ...styles.switchKnob, left: status && status.gatewayEnabled ? 21 : 3 } })))),
+          React.createElement('section', { style: styles.card },
+            React.createElement('div', { style: { display: 'flex', justifyContent: 'space-between', gap: 14, alignItems: 'center' } },
+              React.createElement('div', null,
+                React.createElement('strong', null, '设备鉴权'),
+                React.createElement('div', { style: { ...styles.muted, marginTop: 4 } }, status && status.requireAuth ? '已开启，仅允许可信设备连接' : '已关闭，仅限 Debug 阶段使用')),
+              React.createElement('label', { style: { ...styles.switch, opacity: busy || !status ? .55 : 1 }, title: status && status.requireAuth ? '关闭设备鉴权' : '开启设备鉴权' },
+                React.createElement('input', {
+                  type: 'checkbox',
+                  role: 'switch',
+                  'aria-label': '设备鉴权',
+                  'aria-checked': !!(status && status.requireAuth),
+                  checked: !!(status && status.requireAuth),
+                  disabled: busy || !status,
+                  onChange: toggleAuth,
+                  style: styles.switchInput,
+                }),
+                React.createElement('span', { style: { ...styles.switchTrack, background: status && status.requireAuth ? colors.success : colors.danger } }),
+                React.createElement('span', { style: { ...styles.switchKnob, left: status && status.requireAuth ? 21 : 3 } }))),
+            status && !status.requireAuth
+              ? React.createElement('p', { style: { ...styles.error, margin: '12px 0 0' } }, 'Debug 模式：移动网关连接将跳过设备凭证校验，请勿暴露到公网。')
+              : null),
+          React.createElement('section', { style: styles.card },
+            React.createElement('label', { style: styles.label }, '公网 WebSocket 地址'),
+            React.createElement('input', { style: styles.input, value: publicUrl, onChange: (event) => setPublicUrl(event.target.value), placeholder: 'wss://gateway.example.com/ws/mobile', spellCheck: false }),
+            React.createElement('label', { style: styles.label }, '设备名称'),
+            React.createElement('input', { style: styles.input, value: deviceName, onChange: (event) => setDeviceName(event.target.value), maxLength: 80, placeholder: 'iPhone' }),
+            React.createElement('button', { style: { ...styles.button, ...styles.primary, opacity: busy || !(status && status.gatewayEnabled) ? .65 : 1 }, disabled: busy || !(status && status.gatewayEnabled), onClick: pair }, busy ? '正在生成…' : status && status.gatewayEnabled ? '生成配对二维码' : '请先开启移动网关'),
+            React.createElement('p', { style: { ...styles.muted, margin: '10px 0 0' } }, '公网地址必须使用 wss://。二维码中的配对码只能使用一次，并在 5 分钟内过期。')),
+          qr ? React.createElement('section', { style: { ...styles.card, textAlign: 'center' } },
+            React.createElement('strong', null, '使用 iOS 客户端扫码'),
+            React.createElement('img', { style: styles.qr, src: `data:image/svg+xml;charset=utf-8,${encodeURIComponent(qr.svg)}`, alt: '一次性设备配对二维码' }),
+            React.createElement('label', { style: { ...styles.label, textAlign: 'left' } }, 'Base64URL 配对字符串'),
+            React.createElement('textarea', { style: styles.pairingText, value: qr.qrPayload, readOnly: true, spellCheck: false, onFocus: (event) => event.target.select() }),
+            React.createElement('button', { style: { ...styles.button, width: '100%', marginBottom: 8, borderColor: pairingTokenCopied ? colors.success : colors.border, color: pairingTokenCopied ? colors.success : colors.text }, onClick: copyPairingText }, pairingTokenCopied ? '✓ 已复制' : '复制配对 Token'),
+            pairingTokenCopied ? React.createElement('div', { style: { ...styles.muted, color: colors.success, marginBottom: 8 } }, '已复制到剪贴板') : null,
+            React.createElement('div', { style: styles.muted }, `有效期至 ${new Date(qr.pairing.expiresAt).toLocaleTimeString()}；扫码成功后此二维码立即失效。`)) : null,
+          React.createElement('section', { style: styles.card },
+            React.createElement('div', { style: { display: 'flex', justifyContent: 'space-between', alignItems: 'center' } },
+              React.createElement('strong', null, '可信设备'),
+              React.createElement('div', { style: { display: 'flex', alignItems: 'center', gap: 10 } },
+                deviceNotice || refreshNotice ? React.createElement('span', {
+                  style: { ...styles.muted, color: deviceNoticeError ? colors.danger : colors.success },
+                }, deviceNotice || refreshNotice) : null,
+                React.createElement('button', {
+                  style: { ...styles.button, opacity: refreshing ? .6 : 1 },
+                  disabled: refreshing,
+                  onClick: manualRefresh,
+                }, refreshing ? '刷新中…' : '刷新'))),
+            devices === null
+              ? React.createElement('p', { style: styles.muted }, '加载中…')
+              : devices.length === 0
+                ? React.createElement('p', { style: styles.muted }, '暂无已配对设备。')
+                : devices.map((device) => React.createElement(DeviceRow, {
+                    key: device.id,
+                    device,
+                    onRevoke: revoke,
+                    revoking: revokingIds.has(device.id),
+                  })))))
+    }
+
+    function FooterButton(props) {
+      const isOpen = React.useSyncExternalStore(subscribe, getOpen)
+      const wide = !!props.wide
+      const iconSize = wide ? 16 : 18
+      const icon = React.createElement('svg', {
+        width: iconSize,
+        height: iconSize,
+        viewBox: '0 0 24 24',
+        fill: 'none',
+        stroke: 'currentColor',
+        strokeWidth: 1.8,
+        strokeLinecap: 'round',
+        strokeLinejoin: 'round',
+        'aria-hidden': true,
+      },
+      React.createElement('rect', { x: 6, y: 2, width: 12, height: 20, rx: 2.5 }),
+      React.createElement('path', { d: 'M10 18h4' }))
+      return React.createElement('button', {
+        title: '移动设备管理',
+        'aria-label': '移动设备管理',
+        'aria-pressed': isOpen,
+        onClick: () => setOpen(!isOpen),
+        style: {
+          cursor: 'pointer',
+          background: 'transparent',
+          border: 'none',
+          color: 'inherit',
+          font: 'inherit',
+          display: 'flex',
+          alignItems: 'center',
+          justifyContent: wide ? 'flex-start' : 'center',
+          gap: wide ? 8 : 0,
+          boxSizing: 'border-box',
+          width: wide ? 'calc(100% + 4px)' : 36,
+          height: wide ? 42 : 36,
+          margin: wide ? '4px -2px' : '3px 0',
+          padding: wide ? '0 10px 0 8px' : 0,
+          lineHeight: wide ? '22px' : 'normal',
+        },
+      }, icon, wide ? React.createElement('span', null, '移动设备') : null)
+    }
+
+    function OverlayEntry() {
+      const isOpen = React.useSyncExternalStore(subscribe, getOpen)
+      return isOpen ? React.createElement(DevicePanel) : null
+    }
+
+    const inject = ['slots']
+    function apply(ctx) {
+      ctx.slots.inject('sidebar.footer.action', () => ctx.slots.register(
+        { name: 'sidebar.footer.action', id: 'mobile-gateway-devices', order: 80, label: '移动设备' },
+        (props) => React.createElement(FooterButton, props),
+      ))
+      ctx.slots.inject('shell.overlay', () => ctx.slots.register(
+        { name: 'shell.overlay', id: 'mobile-gateway-devices-panel', order: 100, label: '移动设备' },
+        () => React.createElement(OverlayEntry),
+      ))
+    }
+
+    exports.apply = apply
+    exports.inject = inject
+    return module.exports
+  },
+})

package/lib/devices.js

@@ -0,0 +1,209 @@
+// Persistent paired-device registry for mobile-gateway authentication.
+//
+// Long-lived device tokens are generated with 256 bits of entropy and are
+// never written to disk. Only their SHA-256 digests are persisted. Pairing
+// codes are one-time, short-lived, and memory-only, so a restart invalidates
+// every outstanding QR code without affecting already paired devices.
+'use strict'
+
+const fs = require('node:fs')
+const crypto = require('node:crypto')
+const path = require('node:path')
+
+const STORE_VERSION = 3
+const DEFAULT_PAIRING_TTL_MS = 5 * 60 * 1000
+
+function digest(secret) {
+  return crypto.createHash('sha256').update(secret, 'utf8').digest('hex')
+}
+
+function safeEqualHex(left, right) {
+  if (typeof left !== 'string' || typeof right !== 'string') return false
+  const a = Buffer.from(left, 'hex')
+  const b = Buffer.from(right, 'hex')
+  return a.length === 32 && b.length === 32 && crypto.timingSafeEqual(a, b)
+}
+
+function publicDevice(device, connections) {
+  return {
+    id: device.id,
+    name: device.name,
+    createdAt: device.createdAt,
+    lastSeenAt: device.lastSeenAt || null,
+    online: connections > 0,
+    connections,
+  }
+}
+
+function normalizeClientDeviceId(value) {
+  if (typeof value !== 'string') return undefined
+  const normalized = value.trim()
+  return /^[A-Za-z0-9._:-]{8,128}$/.test(normalized) ? normalized : undefined
+}
+
+function createRegistry(file, options = {}) {
+  const pairingTtlMs = Number.isSafeInteger(options.pairingTtlMs) && options.pairingTtlMs > 0
+    ? options.pairingTtlMs
+    : DEFAULT_PAIRING_TTL_MS
+  let devices = []
+  const pairings = new Map()
+  const online = new Map()
+
+  const save = () => {
+    fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 })
+    const tmp = `${file}.${process.pid}.tmp`
+    fs.writeFileSync(tmp, JSON.stringify({ version: STORE_VERSION, devices }, null, 2), { mode: 0o600 })
+    fs.chmodSync(tmp, 0o600)
+    fs.renameSync(tmp, file)
+  }
+
+  const load = () => {
+    try {
+      const parsed = JSON.parse(fs.readFileSync(file, 'utf8'))
+      if (!Array.isArray(parsed.devices)) return
+      let migrated = false
+      devices = parsed.devices.flatMap((row) => {
+        if (!row || typeof row.id !== 'string' || typeof row.name !== 'string') return []
+        let tokenHash = typeof row.tokenHash === 'string' ? row.tokenHash : undefined
+        // Migrate the v1 development format without invalidating an existing
+        // device. The plaintext is removed on the next atomic save.
+        if (!tokenHash && typeof row.token === 'string' && row.token !== '') {
+          tokenHash = digest(row.token)
+          migrated = true
+        }
+        if (!tokenHash || !/^[a-f0-9]{64}$/.test(tokenHash)) return []
+        return [{
+          id: row.id,
+          name: row.name.slice(0, 80),
+          clientDeviceId: normalizeClientDeviceId(row.clientDeviceId),
+          tokenHash,
+          createdAt: Number.isFinite(row.createdAt) ? row.createdAt : Date.now(),
+          lastSeenAt: Number.isFinite(row.lastSeenAt) ? row.lastSeenAt : null,
+          revokedAt: Number.isFinite(row.revokedAt) ? row.revokedAt : (row.revoked ? Date.now() : null),
+        }]
+      })
+      if (migrated || parsed.version !== STORE_VERSION) save()
+      else fs.chmodSync(file, 0o600)
+    } catch (error) {
+      if (error && error.code !== 'ENOENT') throw new Error(`failed to load device registry: ${error.message}`, { cause: error })
+    }
+  }
+
+  const prunePairings = (now = Date.now()) => {
+    for (const [codeHash, pairing] of pairings) {
+      if (pairing.expiresAt <= now) pairings.delete(codeHash)
+    }
+  }
+
+  load()
+
+  return {
+    list() {
+      return devices
+        .filter((device) => !device.revokedAt)
+        .map((device) => publicDevice(device, online.get(device.id) || 0))
+    },
+
+    count() {
+      return devices.filter((device) => !device.revokedAt).length
+    },
+
+    createPairing(name) {
+      prunePairings()
+      const code = crypto.randomBytes(32).toString('base64url')
+      const pairing = {
+        id: crypto.randomUUID(),
+        name: typeof name === 'string' && name.trim() !== '' ? name.trim().slice(0, 80) : '未命名设备',
+        expiresAt: Date.now() + pairingTtlMs,
+      }
+      pairings.set(digest(code), pairing)
+      return { ...pairing, code }
+    },
+
+    hasPairing(code) {
+      prunePairings()
+      return typeof code === 'string' && pairings.has(digest(code))
+    },
+
+    claimPairing(code, clientDeviceId) {
+      prunePairings()
+      if (typeof code !== 'string' || code === '') return undefined
+      const codeHash = digest(code)
+      const pairing = pairings.get(codeHash)
+      if (!pairing) return undefined
+      // Delete before doing any further work: claiming is single-use even if a
+      // later socket upgrade fails.
+      pairings.delete(codeHash)
+      const token = crypto.randomBytes(32).toString('base64url')
+      const normalizedClientDeviceId = normalizeClientDeviceId(clientDeviceId)
+      let device = normalizedClientDeviceId
+        ? devices.find((candidate) => !candidate.revokedAt && candidate.clientDeviceId === normalizedClientDeviceId)
+        : undefined
+      if (device) {
+        // A valid one-time pairing code authorizes credential rotation. Keep
+        // the stable server-side device record while replacing its token, so
+        // re-pairing one iOS installation never creates duplicate rows.
+        device.name = pairing.name
+        device.tokenHash = digest(token)
+        device.clientDeviceId = normalizedClientDeviceId
+      } else {
+        device = {
+          id: pairing.id,
+          name: pairing.name,
+          clientDeviceId: normalizedClientDeviceId,
+          tokenHash: digest(token),
+          createdAt: Date.now(),
+          lastSeenAt: null,
+          revokedAt: null,
+        }
+        devices.push(device)
+      }
+      save()
+      return { device: publicDevice(device, 0), token }
+    },
+
+    authenticate(token, clientDeviceId) {
+      if (typeof token !== 'string' || token === '') return undefined
+      const tokenHash = digest(token)
+      const device = devices.find((candidate) => !candidate.revokedAt && safeEqualHex(candidate.tokenHash, tokenHash))
+      const normalizedClientDeviceId = normalizeClientDeviceId(clientDeviceId)
+      if (device && normalizedClientDeviceId && !device.clientDeviceId) {
+        // Migration path for devices paired before installation IDs existed:
+        // a valid long-lived token proves ownership of this record, so it is
+        // safe to bind the client's stable ID without creating a new device.
+        const conflict = devices.some((candidate) => candidate !== device && !candidate.revokedAt && candidate.clientDeviceId === normalizedClientDeviceId)
+        if (!conflict) {
+          device.clientDeviceId = normalizedClientDeviceId
+          save()
+        }
+      }
+      return device ? publicDevice(device, online.get(device.id) || 0) : undefined
+    },
+
+    connected(deviceId) {
+      const device = devices.find((candidate) => candidate.id === deviceId && !candidate.revokedAt)
+      if (!device) return false
+      online.set(deviceId, (online.get(deviceId) || 0) + 1)
+      device.lastSeenAt = Date.now()
+      save()
+      return true
+    },
+
+    disconnected(deviceId) {
+      const count = online.get(deviceId) || 0
+      if (count <= 1) online.delete(deviceId)
+      else online.set(deviceId, count - 1)
+    },
+
+    revoke(deviceId) {
+      const index = devices.findIndex((candidate) => candidate.id === deviceId && !candidate.revokedAt)
+      if (index < 0) return false
+      devices.splice(index, 1)
+      online.delete(deviceId)
+      save()
+      return true
+    },
+  }
+}
+
+module.exports = { createRegistry, digest }