dsh-plugin-mobile-link 0.6.6 → 0.8.0

package/lib/dir-listing.js

@@ -0,0 +1,167 @@
+/**
+ * `_link/dirListing`：`workspaceFiles/list` 的同形增强副本，本机补 `mtimeMs`。
+ *
+ * 为什么要它：宿主 `workspaceFiles/list` 的条目只有 `name/type/size?`（宿主类型见
+ * `@deepseek-ai/dsh-api-workspace-files` 的 `WorkspaceDirectoryEntry`），
+ * 没有任何时间字段；`workspaceFiles/stat` 的 `version` 是 opaque token（类型注释明确
+ * "never parsed"），推不出时间。用户要的是"哪个文件最近被动过"，所以由电脑侧补。
+ *
+ * 三条纪律（与 `session-digest.js` 同款）：
+ *   1. **清单的所有者仍是宿主**：连接器只往条目上加一个字段，不删、不改、不重排；
+ *      宿主报错时错误信封逐字透传。
+ *   2. **拿不到就原样返回**：root 缺失/相对/越界、单条目 stat 失败、超出总预算——
+ *      一律退回未增强的原始清单。装饰永不弄坏清单，目录本身一定能打开。
+ *   3. **不提速、不重试**：一个条目最多 stat 一次；没有缓存（mtime 会变，缓存就要失效
+ *      逻辑，而列目录本来就是低频动作）。
+ *
+ * 符号链接用 `fs.stat`（跟随链接）报**目标**的时间——宿主列的 `type`/`size` 本来就是
+ * 按目标解析的（类型注释："A symlink reports the type of its destination"），
+ * `lstat` 报的链接自身时间只在重指时变化，回答不了"内容什么时候改的"。
+ */
+
+import { stat } from 'node:fs/promises'
+import { isAbsolute, resolve, sep } from 'node:path'
+
+/** 方法名（设备发起；`_link/` 前缀 = 连接器自答，永不转发宿主）。 */
+export const DIR_LISTING_METHOD = '_link/dirListing'
+
+/** 宿主的清单方法：连接器只读它，不改它。 */
+const HOST_LIST_METHOD = 'workspaceFiles/list'
+
+/** 可调的上限。`statBudgetMs` 是全部条目补时间的总预算（见 §2.2 失败语义表）。 */
+export const LIMITS = Object.freeze({
+  statBudgetMs: 2000,
+})
+
+export function isDirListingMethod(method) {
+  return method === DIR_LISTING_METHOD
+}
+
+/**
+ * 给一份宿主目录清单补上 `mtimeMs`。
+ *
+ * 认两种输入形状（与 `digestSessionList` 同款）：宿主信封 `{ ok, value: { entries } }`
+ * 以及直接给的 `{ entries }`。**返回的始终是同形状的值**，调用方不必再猜信封在哪一层。
+ * 结构不是预期的样子就原样返回入参——装饰不许把"看不懂"变成"改掉"。
+ *
+ * @param {object} options
+ * @param {{ rpc: (method: string, args: object) => Promise<unknown> }} options.dsh 宿主 RPC
+ * @param {object} options.args 设备发来的参数（`workspaceFileScopeId` / `path` / `root`）
+ * @param {{ debug?: (message: string) => void, warn?: (message: string) => void }} [options.logger]
+ * @param {(path: string) => Promise<{ mtimeMs: number }>} [options.statImpl] 可注入，供单测
+ * @param {number} [options.budgetMs] 总预算，缺省 `LIMITS.statBudgetMs`
+ * @returns {Promise<unknown>} 增强后的同形值；降级时是原始值
+ */
+export async function dirListing({ dsh, args, logger, statImpl = stat, budgetMs = LIMITS.statBudgetMs }) {
+  const request = args ?? {}
+  const result = await dsh.rpc(HOST_LIST_METHOD, {
+    workspaceFileScopeId: request.workspaceFileScopeId,
+    path: typeof request.path === 'string' ? request.path : '.',
+  })
+
+  const entries = listingEntries(result)
+  if (entries === null) {
+    logger?.debug?.('dir-listing: host answered a shape this connector does not decorate')
+    return result
+  }
+
+  const directory = resolveDirectory(request.root, entries.path)
+  if (directory === null) {
+    // root 缺失 / 非绝对 / 宿主回的 path 越出 root：不是错误，只是补不了时间。
+    logger?.debug?.(`dir-listing: cannot resolve the listed directory from root ${JSON.stringify(request.root)}`)
+    return result
+  }
+
+  const decorated = await withBudget(
+    Promise.all(entries.items.map((entry) => decorate(entry, directory, statImpl))),
+    budgetMs
+  )
+  if (decorated === null) {
+    logger?.warn?.(`dir-listing: stat budget of ${budgetMs}ms ran out, answering the plain listing`)
+    return result
+  }
+  return replaceEntries(result, decorated)
+}
+
+/**
+ * 取出清单本体（`{ entries: [...], path }`），形状不对时返回 null。
+ *
+ * 信封可能是 `result` 本身，也可能是 `result.value`——按"哪一层有 entries 数组"判定，
+ * 与 `digestSessionList` 同一读法。
+ */
+function listingEntries(result) {
+  if (result === null || typeof result !== 'object') return null
+  if (result.ok !== true) return null
+  const container = Array.isArray(result.entries) ? result : result.value
+  if (container === null || typeof container !== 'object' || !Array.isArray(container.entries)) return null
+  return { path: container.path, items: container.entries }
+}
+
+/** 按原形状放回增强后的条目数组。 */
+function replaceEntries(result, items) {
+  if (Array.isArray(result.entries)) return { ...result, entries: items }
+  return { ...result, value: { ...result.value, entries: items } }
+}
+
+/**
+ * 宿主回的 `path` 词法解析成绝对目录；解析不了（要求降级）时返回 null。
+ *
+ * - `path` 可以是相对的（`""` 表根、`"docs"`）也可以是绝对的（App/宿主都有先例）。
+ * - 结果必须位于 root 之内：`resolved === root || resolved.startsWith(root + sep)`。
+ *   只比 `startsWith(root)` 会把 `/a/b-sibling` 当成 `/a/b` 的子路径。
+ * - **不做 realpath 越界拦截**（设计 §2.2 决策 1）：符号链接的目标可以合法地在工作区
+ *   之外，宿主今天已经按目标报 `type`/`size`，这里保持同一语义。
+ */
+function resolveDirectory(root, echoedPath) {
+  if (typeof root !== 'string' || !isAbsolute(root)) return null
+  const base = resolve(root)
+  const echoed = typeof echoedPath === 'string' ? echoedPath : ''
+  const resolved = isAbsolute(echoed) ? resolve(echoed) : resolve(base, echoed)
+  if (resolved !== base && !resolved.startsWith(base + sep)) return null
+  return resolved
+}
+
+/**
+ * 一条条目：stat 成功且时间可用就加 `mtimeMs`，其余情况原样返回。
+ *
+ * 条目名逐段校验：含 `/`、`\` 或等于 `.` / `..` 的名字直接跳过（宿主契约说是 basename，
+ * 这里是纵深防御，防的是异常回包，不是防用户）。跳过的意思是"不给它补时间"，
+ * **不是把条目从清单里删掉**——清单的所有者是宿主。
+ */
+async function decorate(entry, directory, statImpl) {
+  if (entry === null || typeof entry !== 'object') return entry
+  if (typeof entry.name !== 'string' || !isPlainName(entry.name)) return entry
+  try {
+    const info = await statImpl(resolve(directory, entry.name))
+    const mtimeMs = info?.mtimeMs
+    if (typeof mtimeMs !== 'number' || !Number.isFinite(mtimeMs)) return entry
+    const rounded = Math.round(mtimeMs)
+    if (!Number.isFinite(rounded)) return entry
+    return { ...entry, mtimeMs: rounded }
+  } catch {
+    // 断链、权限、竞态删除：这个条目没有时间，其余条目照旧。
+    return entry
+  }
+}
+
+function isPlainName(name) {
+  return name.length > 0 && name !== '.' && name !== '..' && !name.includes('/') && !name.includes('\\')
+}
+
+/**
+ * 给整批 stat 一个总预算。超时返回 `null`（调用方据此降级），
+ * **不取消**后台的 stat——它们会自然收尾，取消反而要给每条挂一个 signal。
+ */
+async function withBudget(work, budgetMs) {
+  if (!(budgetMs > 0)) return await work
+  let timer
+  const expiry = new Promise((resolve) => {
+    timer = setTimeout(() => resolve(null), budgetMs)
+  })
+  try {
+    const outcome = await Promise.race([work, expiry])
+    return outcome === null ? null : outcome
+  } finally {
+    clearTimeout(timer)
+  }
+}

package/lib/dlp.js

@@ -6,6 +6,8 @@
  * Wire contract: docs/RELAY-PROTOCOL.md §3.
  */
 
+import { repairLoneSurrogatesWithCount } from './unicode.js'
+
 /** Frame ceiling aligned with DSH's image-attachment limit (spec §5). */
 export const MAX_FRAME_BYTES = 32 * 1024 * 1024
 
@@ -40,8 +42,23 @@ export const RELAY_TO_AGENT_CONTROL = new Set(['fsGetCancel'])
 
 const ID_FRAMES = new Set(['req', 'open', 'cancel', 'res', 'item', 'end', 'streamError', 'eventResult'])
 
+/**
+ * 出站帧的唯一序列化出口。
+ *
+ * 为什么要过一遍代理项修复：宿主会给我们**截断过**的预览（`turnOutline` 的
+ * prompt/response 截到 50/120 个码元），截断点落在 emoji 中间时字符串里就有
+ * 落单代理项，`JSON.stringify` 会忠实写成 `"\ud83d…"`。中转能把它修回 U+FFFD，
+ * 但解码方（iOS `JSONDecoder`）遇到这种转义会整条拒绝，所以生产端先把帧修好。
+ */
 export function encodeFrame(frame) {
-  return JSON.stringify(frame)
+  return encodeFrameChecked(frame).text
+}
+
+/** `encodeFrame` 的带诊断版本：`repaired` 是这条帧里修掉的落单代理项条数。 */
+export function encodeFrameChecked(frame) {
+  const raw = JSON.stringify(frame)
+  const { text, repaired } = repairLoneSurrogatesWithCount(raw)
+  return { text, repaired }
 }
 
 /**
@@ -176,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
- * (`relay/admin.py 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/api.py), 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(' ')
 }