dsh-plugin-mobile-link 0.7.0 → 0.8.0

package/lib/dlp.js

@@ -193,6 +193,21 @@ export function pairCodeRegenerateEndpoint(relayUrl) {
   return joinRelayPath(normalizeRelayUrl(relayUrl).httpBase, 'pair/code/regenerate')
 }
 
+/** List every paired device for this agent (`GET /devices`, agent secret). */
+export function deviceListEndpoint(relayUrl) {
+  return joinRelayPath(normalizeRelayUrl(relayUrl).httpBase, 'devices')
+}
+
+/** Revoke one paired device for this agent (`POST /devices/revoke`, agent secret). */
+export function deviceRevokeEndpoint(relayUrl) {
+  return joinRelayPath(normalizeRelayUrl(relayUrl).httpBase, 'devices/revoke')
+}
+
+/** Backfill the machine MAC for an already enrolled agent (`POST /agents/machine`). */
+export function agentMachineEndpoint(relayUrl) {
+  return joinRelayPath(normalizeRelayUrl(relayUrl).httpBase, 'agents/machine')
+}
+
 /** The relay's self-service enrollment endpoint (`POST /agents/enroll`). */
 export function enrollEndpoint(relayUrl) {
   return joinRelayPath(normalizeRelayUrl(relayUrl).httpBase, 'agents/enroll')

package/lib/enroll.js

@@ -1,24 +1,136 @@
 /**
- * First-run enrollment: turn an invite code into a durable agent identity.
+ * First-run enrollment: turn a relay address into a durable agent identity.
  *
- * Until now an identity could only be provisioned by whoever owns the relay
- * (`dsh-relay admin agent-register --write-config`). That does not distribute:
- * somebody else installs DSH plus this connector on their own computer and has
- * to be handed a credential by the operator, out of band.
- *
- * So the relay grew `POST /agents/enroll` (relay-go/internal/httpapi), which redeems a
- * one-time invite code for a fresh `agentId` / `agentSecret`. This module is the
- * connector half: one call, then the identity is written to the same
+ * An identity used to require an invite code from the relay operator. Enrollment
+ * is now open: `POST /agents/enroll` (relay-go/internal/httpapi) creates the
+ * account and computer, rate-limited by source. This module is the connector
+ * half: one call, then the identity is written to the same
  * `~/.dsh/mobile-link/agent.json` (mode 0600) that `agent-register` writes, so
  * nothing downstream can tell the two apart.
  *
- * Enrollment is deliberately *not* automatic against an open endpoint: an
- * invite code must be present, because the relay is on the public internet.
+ * The optional `inviteCode` path remains only as a compatibility shim for old
+ * deployments and old callers; new installs do not use it.
  */
 
-import { enrollEndpoint } from './dlp.js'
+import { execFileSync } from 'node:child_process'
+import { hostname, networkInterfaces } from 'node:os'
+
+import { agentMachineEndpoint, enrollEndpoint, isPlaceholderRelayUrl, normalizeRelayUrl } from './dlp.js'
 import { DEFAULT_AGENT_NAME, INVITE_ENV, defaultStatePath, readState, writeState } from './state.js'
 
+/**
+ * Normalize a MAC-48 address to uppercase colon form.
+ * Returns '' for anything that is not a MAC.
+ */
+export function normalizeMacAddress(value) {
+  const compact = String(value ?? '').trim().replace(/[-.:\s]/g, '').toUpperCase()
+  if (!/^[0-9A-F]{12}$/.test(compact)) return ''
+  return compact.match(/.{2}/g).join(':')
+}
+
+/**
+ * Pick the computer's primary physical interface MAC.
+ *
+ * This is an *identifier*, not an authenticator: a MAC can be spoofed. It is
+ * used only so the relay can associate repeat enrollments of the same machine.
+ * Virtual/VPN interfaces are skipped (they change or reflect tunnels), and
+ * common primary interface names win over the rest. If nothing is found the
+ * field is omitted rather than inventing a value.
+ */
+export function primaryMacAddress(interfaces) {
+  // macOS 的 Node 经常只拿到 02:00:00:00:00:00（系统隐私/沙箱占位），
+  // 而 networksetup 仍能读到真实硬件地址；优先向它要，读不到再走接口枚举。
+  if (interfaces === undefined && process.platform === 'darwin') {
+    const mac = darwinMacAddress()
+    if (mac) return mac
+  }
+  const virtual = /^(lo|docker|veth|br-|virbr|vmnet|vboxnet|utun|tun|tap|wg|tailscale|zt|bridge|awdl|llw)/i
+  const preferred = /^(en0|eth0|wlan0|wi-?fi|ethernet)$/i
+  const seen = new Set()
+  const candidates = []
+  for (const [name, entries] of Object.entries(interfaces ?? networkInterfaces())) {
+    if (!entries || virtual.test(name)) continue
+    for (const entry of entries) {
+      if (!entry || entry.internal) continue
+      const mac = normalizeMacAddress(entry.mac)
+      if (!mac || mac === '00:00:00:00:00:00' || mac === '02:00:00:00:00:00' || seen.has(mac)) continue
+      seen.add(mac)
+      candidates.push({ name, mac, preferred: preferred.test(name) ? 0 : 1 })
+    }
+  }
+  candidates.sort((a, b) => a.preferred - b.preferred || a.name.localeCompare(b.name))
+  return candidates[0]?.mac ?? ''
+}
+
+/// macOS 的硬件端口表是唯一能稳定拿到真实 MAC 的入口：Node 的
+/// `os.networkInterfaces()` 在部分系统上被隐私层替换成 02:00:00:00:00:00。
+function darwinMacAddress() {
+  const activeDevice = darwinDefaultInterface()
+  let output
+  try {
+    output = execFileSync('/usr/sbin/networksetup', ['-listallhardwareports'], {
+      encoding: 'utf8', timeout: 2000, stdio: ['ignore', 'pipe', 'ignore'],
+    })
+  } catch {
+    return ''
+  }
+  const blocks = []
+  let current = {}
+  const flush = () => {
+    if (current.mac) blocks.push(current)
+    current = {}
+  }
+  for (const line of output.split('\n')) {
+    const match = line.match(/^\s*(Hardware Port|Device|Ethernet Address):\s*(.+?)\s*$/)
+    if (!match) continue
+    if (match[1] === 'Hardware Port') {
+      flush()
+      current.port = match[2]
+    }
+    if (match[1] === 'Device') current.device = match[2]
+    if (match[1] === 'Ethernet Address') current.mac = normalizeMacAddress(match[2])
+  }
+  flush()
+  const active = blocks.find((block) => block.device === activeDevice)
+  if (active?.mac) return active.mac
+  const preferred = /(wi-?fi|ethernet|lan)/i
+  const chosen = blocks.find((block) => preferred.test(block.port ?? block.device ?? ''))
+  return chosen?.mac ?? blocks[0]?.mac ?? ''
+}
+
+/// 默认路由对应的接口：优先用它，避免机器同时插网线和 Wi-Fi 时选到未使用的网口。
+function darwinDefaultInterface() {
+  try {
+    const output = execFileSync('/sbin/route', ['-n', 'get', 'default'], {
+      encoding: 'utf8', timeout: 2000, stdio: ['ignore', 'pipe', 'ignore'],
+    })
+    return output.match(/^\s*interface:\s*(\S+)/m)?.[1] ?? ''
+  } catch {
+    return ''
+  }
+}
+
+/**
+ * A failed enrollment, tagged with a machine-readable code.
+ *
+ * The CLI prints `.message`; the panel maps `.code` to Chinese copy. Keeping both
+ * on one error is deliberate: the relay's three invite failures need different
+ * advice, and the UI must not re-parse English text to find out which one it got.
+ */
+export class EnrollError extends Error {
+  constructor(code, message, { status, retryable = false, stateFile } = {}) {
+    super(message)
+    this.name = 'EnrollError'
+    this.code = code
+    this.status = status
+    this.retryable = Boolean(retryable)
+    if (stateFile) this.stateFile = stateFile
+  }
+}
+
+/** How long a relay may take to answer an enrollment before it is called stuck. */
+export const ENROLL_TIMEOUT_MS = 15000
+
 /** Where the invite code may come from: explicit argument, then environment. */
 export function inviteFrom({ inviteCode, env = process.env } = {}) {
   const value = typeof inviteCode === 'string' && inviteCode.trim() ? inviteCode : env?.[INVITE_ENV]
@@ -40,7 +152,7 @@ export async function enrollPlan({ stateFile, inviteCode, relayUrl, env = proces
   }
   const invite = inviteFrom({ inviteCode, env })
   const relay = relayUrl || env?.DSH_MOBILE_LINK_RELAY || ''
-  return { needed: true, stateFile: path, invite, relayUrl: relay, canEnroll: Boolean(invite && relay) }
+  return { needed: true, stateFile: path, invite, relayUrl: relay, canEnroll: Boolean(relay) }
 }
 
 /**
@@ -58,55 +170,156 @@ export async function enrollPlan({ stateFile, inviteCode, relayUrl, env = proces
  * @returns {Promise<{agentId: string, agentSecret: string, agentName: string, relayUrl: string, stateFile: string}>}
  */
 export async function enrollAgent({
-  relayUrl, inviteCode, name, stateFile, deviceName,
-  fetchImpl = fetch, logger = undefined,
+  relayUrl, inviteCode, name, stateFile, deviceName, macAddress,
+  fetchImpl = fetch, logger = undefined, timeoutMs = ENROLL_TIMEOUT_MS,
 } = {}) {
-  if (!inviteCode || !String(inviteCode).trim()) {
-    throw new Error('mobile-link: an invite code is required to enroll (--invite <code>)')
-  }
+  const invite = typeof inviteCode === 'string' ? inviteCode.trim() : ''
   if (!relayUrl || !String(relayUrl).trim()) {
-    throw new Error('mobile-link: a relay URL is required to enroll (--relay <url>)')
+    throw new EnrollError('enroll/bad-request', 'mobile-link: a relay URL is required to enroll (--relay <url>)')
+  }
+  // Validate before the network call: a typo in the relay address should not
+  // look like a rejected invite, and the placeholder shipped in the repository
+  // must never be dialed as if it were a deployment.
+  try {
+    normalizeRelayUrl(relayUrl)
+  } catch (error) {
+    throw new EnrollError('enroll/invalid-relay',
+      `mobile-link: invalid relay URL ${JSON.stringify(relayUrl)}: ${messageOf(error)}`)
   }
+  if (isPlaceholderRelayUrl(relayUrl)) {
+    throw new EnrollError('enroll/placeholder-relay',
+      'mobile-link: the relay address is the repository placeholder; use the address your provider gave you')
+  }
+
   const path = stateFile || defaultStatePath()
-  const agentName = (name || deviceName || '').trim() || DEFAULT_AGENT_NAME
+  const agentName = (name || deviceName || '').trim() || hostname().trim() || DEFAULT_AGENT_NAME
+  const machineMac = normalizeMacAddress(macAddress ?? primaryMacAddress())
+  const waitMs = Number.isFinite(Number(timeoutMs)) && Number(timeoutMs) > 0
+    ? Number(timeoutMs)
+    : ENROLL_TIMEOUT_MS
+
+  // `Promise.race` rather than relying on the signal alone: an injected fetch
+  // (or a runtime that does not honour AbortSignal) must still surface a
+  // timeout instead of leaving the panel on "登记中" forever.
+  const controller = new AbortController()
+  let timer
+  const timeout = new Promise((_, reject) => {
+    timer = setTimeout(() => {
+      controller.abort()
+      reject(new EnrollError('enroll/timeout',
+        `mobile-link: the relay did not answer within ${waitMs} ms`, { retryable: true }))
+    }, waitMs)
+    // Deliberately NOT unref'd: if an injected fetch holds no handle, an unref'd
+    // timer lets Node decide the event loop is empty and exit with the promise
+    // still pending (caught by the Linux L2 run). The timer is cleared on every
+    // settled fetch, so it only keeps the process alive while a request is
+    // genuinely outstanding.
+  })
 
   let response
   try {
-    response = await fetchImpl(enrollEndpoint(relayUrl), {
-      method: 'POST',
-      headers: { 'content-type': 'application/json' },
-      body: JSON.stringify({ inviteCode: String(inviteCode).trim(), name: agentName }),
-    })
+    response = await Promise.race([
+      fetchImpl(enrollEndpoint(relayUrl), {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        // 有邀请码就带上（老的邀请码发放方式仍可用）；没有就是开放登记。
+        body: JSON.stringify({
+          ...(invite ? { inviteCode: invite } : {}),
+          name: agentName,
+          ...(machineMac ? { macAddress: machineMac } : {}),
+        }),
+        signal: controller.signal,
+      }),
+      timeout,
+    ])
   } catch (error) {
-    throw new Error(`mobile-link: cannot reach the relay at ${relayUrl}: ${messageOf(error)}`)
+    if (error instanceof EnrollError) throw error
+    throw new EnrollError('enroll/unreachable',
+      `mobile-link: cannot reach the relay at ${relayUrl}: ${messageOf(error)}`, { retryable: true })
+  } finally {
+    clearTimeout(timer)
   }
 
   let body
   try {
     body = await response.json()
   } catch {
-    throw new Error(`mobile-link: the relay answered HTTP ${response.status} to /agents/enroll`)
+    throw new EnrollError('enroll/bad-response',
+      `mobile-link: the relay answered HTTP ${response.status} to /agents/enroll`,
+      { status: response.status })
   }
   if (!response.ok || body?.ok !== true || !body.agentId || !body.agentSecret) {
-    throw new Error(describeEnrollFailure(body, response.status))
+    const code = body?.error?.code
+    throw new EnrollError(typeof code === 'string' && code ? code : 'enroll/relay-error',
+      describeEnrollFailure(body, response.status), {
+        status: response.status,
+        retryable: code === 'enroll/rate-limited' || code === 'enroll/store-error' || code === 'internal/error',
+      })
   }
 
-  await writeState(path, {
-    relayUrl,
-    agentId: body.agentId,
-    agentSecret: body.agentSecret,
-    agentName: body.agentName || agentName,
-  })
+  try {
+    await writeState(path, {
+      relayUrl,
+      agentId: body.agentId,
+      agentSecret: body.agentSecret,
+      agentName: body.agentName || agentName,
+    })
+  } catch (error) {
+    // The code has already been redeemed at this point. Say so explicitly:
+    // retrying with the same code will fail with "already used", and the person
+    // needs to know the identity could not be saved (and where).
+    throw new EnrollError('enroll/state-write',
+      `mobile-link: the identity was redeemed but could not be saved to ${path}: ${messageOf(error)}`,
+      { stateFile: path })
+  }
   logger?.info?.(`mobile-link: enrolled as ${body.agentId} (${body.agentName || agentName})`)
   return {
     agentId: body.agentId,
     agentSecret: body.agentSecret,
     agentName: body.agentName || agentName,
+    macAddress: body.macAddress || machineMac,
     relayUrl,
     stateFile: path,
   }
 }
 
+/**
+ * Backfill the MAC for an identity enrolled before the relay stored one.
+ *
+ * Runs on every connector start, authenticated with the agent secret. The relay
+ * only fills an empty slot, so a later network/interface change cannot rewrite
+ * the machine index. An old relay answers 404: that is "not supported", not a
+ * connection failure, and startup must continue.
+ */
+export async function reportMachineAddress({
+  relayUrl, agentSecret, macAddress, fetchImpl = fetch, timeoutMs = 8000,
+} = {}) {
+  const mac = normalizeMacAddress(macAddress ?? primaryMacAddress())
+  if (!mac || !relayUrl || !agentSecret) return { ok: false, skipped: 'missing-mac-or-identity' }
+  const controller = new AbortController()
+  const timer = setTimeout(() => controller.abort(), timeoutMs)
+  try {
+    const response = await fetchImpl(agentMachineEndpoint(relayUrl), {
+      method: 'POST',
+      headers: {
+        'content-type': 'application/json',
+        authorization: `Bearer ${agentSecret}`,
+      },
+      body: JSON.stringify({ macAddress: mac }),
+      signal: controller.signal,
+    })
+    let body
+    try { body = await response.json() } catch { body = undefined }
+    if (response.status === 404) return { ok: false, unsupported: true, macAddress: mac }
+    if (!response.ok || body?.ok !== true) {
+      throw new Error(body?.error?.message ?? `mobile-link: the relay rejected the machine MAC (HTTP ${response.status})`)
+    }
+    return { ok: true, macAddress: body.macAddress || mac, updated: body.updated === true }
+  } finally {
+    clearTimeout(timer)
+  }
+}
+
 /**
  * Turn the relay's failure into something a person can act on.
  *
@@ -132,7 +345,8 @@ export function describeEnrollFailure(body, status) {
 
 /** The one-liner a fresh install runs, quoted for copy/paste. */
 export function enrollCommand(relayUrl, name = undefined) {
-  const parts = ['dsh-mobile-link enroll', `--relay ${relayUrl || '<relay-url>'}`, '--invite <code>']
+  // 开放登记后命令不再必须带激活码；老的邀请码仍可用 `--invite` 传。
+  const parts = ['dsh-mobile-link enroll', `--relay ${relayUrl || '<relay-url>'}`]
   if (name) parts.push(`--name ${JSON.stringify(name)}`)
   return parts.join(' ')
 }

package/lib/hello.js

@@ -65,7 +65,7 @@ export function hostVersion() {
  * - `qr-pairing`     this connector renders the pairing QR itself (the `svg`
  *                    field of `POST /mobile-link/pair-code`), so the DSH client
  *                    needs no QR library of its own
- * - `self-enroll`    this connector can register itself with an invite code
+ * - `self-enroll`    this connector can register itself without an invite code
  * - `git`            git status / diff / log / show can be read from the work
  *                    tree on this computer (see git.js)
  * - `background-transfer`

package/lib/index.js

@@ -4,8 +4,8 @@
  * Scope (deliberately tiny so a DSH upgrade can never make it fatal):
  *   1. Run the DLP agent: dial the relay over WSS, serve the iOS client's
  *      session/event traffic from the local DSH instance. On a computer that has
- *      never been registered, redeem the invite code from the environment (or
- *      the config) first, so a fresh install becomes usable without the relay
+ *      never been registered, enroll with the relay address first (open
+ *      enrollment), so a fresh install becomes usable without the relay
  *      operator provisioning anything by hand.
  *   2. Two routes under `/mobile-link` behind DSH's own connection fence:
  *      GET  /status     — is the link up, which devices are attached, and is
@@ -43,6 +43,10 @@ const DEFAULTS = {
   relayUrl: process.env.DSH_RELAY_URL
     || process.env.DSH_MOBILE_LINK_RELAY
     || 'wss://relay.example.com/dsh-link',
+  // 面板的默认中转：只用于预填，不参与拨号优先级。它和 `relayUrl` 分开，是因为
+  // 把地址钉进 `relayUrl` 会覆盖身份文件里真正登记过的地址；这里只给表单一个
+  // 可修改的初值。
+  defaultRelayUrl: process.env.DSH_DEFAULT_RELAY_URL || '',
   agentId: '',
   agentSecret: '',
   stateFile: '',
@@ -101,6 +105,9 @@ function buildAgent(config, logger) {
   return new MobileLinkAgent({
     enabled: config.enabled !== false,
     relayUrl: typeof config.relayUrl === 'string' ? config.relayUrl : DEFAULTS.relayUrl,
+    defaultRelayUrl: typeof config.defaultRelayUrl === 'string'
+      ? config.defaultRelayUrl
+      : DEFAULTS.defaultRelayUrl,
     agentId: typeof config.agentId === 'string' ? config.agentId : '',
     agentSecret: typeof config.agentSecret === 'string' ? config.agentSecret : '',
     stateFile: typeof config.stateFile === 'string' && config.stateFile ? config.stateFile : undefined,