dsh-mobile-plugin 0.0.0-stage → 0.1.58

package/README.md

@@ -1,3 +1,160 @@
-# Temporary Holding Version
+# dsh-mobile-plugin
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+AI-HUB 手机端的对端插件，同时充当**无头 Cordis Host**：它自带 Host 进程入口，提供 relay v2
+隧道客户端、局域网代理，以及受限的 `/api/mobile/v1/*` 移动 API。本包**不依赖任何桌面外壳或
+Electron 运行时**，`node host.js` 即可独立运行。
+
+`POST /api/mobile/v1/session/new` 的 body 支持 `workspaceId` 或 `cwd`（二选一，前者优先）：传 `workspaceId` 时宿主会把新会话 attach 到该项目账上，宿主项目列表下立即可见；仅传 `cwd` 时会话归入宿主「未分组」。
+
+`POST /api/mobile/v1/workspace/move-session` 透传宿主 `workspace.insertSessionBefore`，移动端拖动会话排序会同步写入宿主工作区。
+
+设备级实时兼容出口：`GET /api/mobile/v1/events/stream`（Bearer token）以 SSE 转发宿主 `events.mux` 的所有设备事件。每帧包装为 `{ type: "device/event", version: 1, eventId, sessionId?, rpcId?, payload }`；`payload` 保留原 mux 负载，旧的 `/session/stream` 与 relay 协议不变。`session/event` 的 `eventId` 为 `${sessionId}:${event.seq}`，其他帧使用连接内序号。工作区变更是否可见取决于宿主 mux 是否发布对应帧；当前插件没有额外伪造工作区事件。
+
+## 无头部署
+
+部署到 Linux 服务器（无桌面环境）时的要点，完整 runbook 见仓库根 [`../README.md`](../README.md) 的「服务器部署」。
+
+**目录布局不能漏掉凭据库。** 设备凭据库 `dsh-mobile-credentials` 就在本包目录内部（发布时它仍是独立的一个包，装进来后嵌在插件目录里），代码用包内相对路径引用它：
+
+```js
+lib/impl.js:26           require('../dsh-mobile-credentials/lib/credentials.js')
+lib/mobile/auth.js:15    require('../../dsh-mobile-credentials/lib/credentials.js')
+```
+
+```
+/opt/dsh-mobile/
+├── dsh-mobile-plugin/
+│   └── dsh-mobile-credentials/   # 嵌在插件目录内，漏掉就启动即崩
+└── dsh-mobile-server/
+```
+
+> **用 pnpm 装，不要加 `--legacy-peer-deps`。**
+>
+> 本包的 `pnpm-lock.yaml` 是入库的依赖锁，而 pnpm 的 `autoInstallPeers` 会把 peer 冲突
+> 一起解掉：`cordis-plugin-hmr@1.0.19` 要 `@deepseek-ai/cordis@~4.0.4`，锁里解析到的
+> 正是 4.0.4。
+>
+> 这份文档以前教的是 `npm install --legacy-peer-deps`。那个参数只是让 npm 跳过 peer
+> 冲突检查，不是解决冲突；仓库里又没有 `package-lock.json`，也就是说那次安装**什么都
+> 没锁住**——每次干净安装解析出的树都可能不同。
+
+```sh
+cd dsh-mobile-plugin
+pnpm install --frozen-lockfile     # 锁文件与 package.json 不同步时直接失败，而不是悄悄升级
+```
+
+> 锁与 `package.json` 的一致性由 `dsh-mobile-plugin/test/lockfile-sync.test.cjs` 守住。
+> 真要让 cordis 对齐到别的版本，改 `package.json` 后跑一次 `pnpm install` 把锁更新进来。
+
+**启动与数据根：**
+
+```sh
+DSH_HOME=/opt/dsh-mobile/.dsh DSH_MOBILE_PROFILE=mobile node host.js
+# → dsh-mobile-plugin: mobile host ready (profile mobile)
+```
+
+`DSH_HOME` 决定数据根（profile、relay 配置、会话），不设则用 `~/.dsh`；`DSH_MOBILE_PROFILE`
+决定 profile 名（默认 `mobile`），文件生成在 `$DSH_HOME/profiles/<name>/`。
+
+**Web 端口固定 `3080` 且只绑 `127.0.0.1`**（`webserver` 行的端口表达式是 `ctx.webStartup.port ?? 3080`，
+而 `host.js` 传空命令行参数，因此 `--port` 无效）。无头模式的 `web-runtime` 行关闭了
+`openBrowser`/`printUrl`，所以**启动日志不会打印端口**，这不是故障。
+
+## 安装与更新
+
+本包有两条完全不同的安装路径，别混用。
+
+**服务器 / 无头部署：源码同步。** 直接把仓库目录 rsync 到 `/opt/dsh-mobile/`，依赖只在首次装
+或 `package.json` 变了时重装，然后 `systemctl restart dsh-mobile-host`。这条路的版本号不参与
+任何判断，`package.json` 里的 version 写成什么都不会影响宿主行为。
+
+**桌面端：从 npm 装，更新交给 DSH 的插件市场。**（2026-10 改的：此前是本包自带的 OTA +
+「稳定外壳 + 可热替换的代」，那套已经删掉。）
+
+- 包名 `dsh-mobile-plugin`，凭据库 `dsh-mobile-credentials` **内联在本包里**（`files` 收它），
+  所以只发一个包、只有一个版本号要管。
+- 装/更新都在 DSH 里做：**设置 → 插件**（插件市场）里安装或更新本插件，底层就是 profile 里
+  跑一次 pnpm。装了之后「设置 → 移动端 → 打开配置页面」那一页的更新卡片会直接调市场的公共
+  更新接口（`/dsh-market/api/v1/*`），能在页面上检查更新、开始更新、看进度，并在需要时请
+  市场代劳重启 DSH。
+- **装完/更新完要完整重启 DSH**：插件是 profile 层的 cordis bundle，进程起来时依赖树就定死了。
+  市场会把这件事报成 `restartRequired`，页面上有对应提示与按钮。
+- 如果「设置 → 移动端 → 打开配置页面」打不开、页面吐一段 `panel_missing` JSON：那段文案会
+  写清是**哪一种**读不到 —— 「装完没重启」（旧实例还挂在这次安装删掉的那个目录上，最常见）、
+  「装了老版本」（0.1.47 及更早还没有这一页）还是「真没构建」（源码树里才会遇到）。三种解法
+  不同，别照着「没重启」的现场去跑 React 构建。同一句话也会进宿主 stderr。
+- 从前那套的教训记在这里：热更新只换宿主侧的实现代，**换不掉设置菜单那一半**（渲染器直接从
+  安装目录读它），于是出现过「更新报成功、界面一动不动」，重启 DSH、重启 sidecar 都没用。
+  现在只有一条更新路径，这类「哪一半是旧的」不再存在。
+
+### 发版流程（自己发一版更新）
+
+1. **抬版本号**：`node scripts/bump-version.mjs`（三段各 `0..999`）。
+2. **改过 `React/` 就先重建面板**：`cd React && pnpm run build`。产物 `lib/panel/index.html`
+   是**提交物**，要和源码一起提交 —— 忘了重建，发出去的就是旧页面，而仓库里没有任何东西能
+   替你发现（守卫只比字节形状，不比新旧）。
+3. **自检**：`npm test`（其中 `panel-artifact` 管产物形状与「读不到时报什么」，
+   `publish-payload` 管发布清单收得住每个会被加载的文件）；`npm pack --dry-run` 扫一眼发了什么。
+4. **发布**：`npm publish`。
+5. **核对**：`npm view dsh-mobile-plugin version`。
+6. **到机器上更新**：DSH → 设置 → 插件 里更新，**然后完整重启 DSH**。
+
+**发布这一步现在要你现场过二次验证**（2026-10 起，别以为是配错了）：
+
+- `npm publish` 会打印一条 `https://www.npmjs.com/auth/cli/…` 链接（或直接开浏览器），用账号
+  绑定的**安全密钥**确认一下，它自己接着把包发出去。
+- 所以这一步**必须能打开 www.npmjs.com**：机房/代理出口 IP 会被它的反机器人拦成 403
+  （页面写「访问暂时受限」并带上你的 IP）。换个节点或直连再发。
+- npm 已经关掉了「命令行建号」和「验证器 App（TOTP）」两条路：建号只能在网页上做，2FA 只能挂
+  安全密钥。这两件事上试命令是白费时间，认它就行。
+- 想少点一次确认，可以建一把「允许绕过 2FA」的细粒度令牌少输几次验证：
+  `npm token create --bypass-2fa --packages dsh-mobile-plugin --packages-and-scopes-permission read-write --expires 90`
+  （**最长 90 天**）。代价：这类令牌 **2027-01 起不能再直接发布**，到期或到点都得回到上面
+  那条交互式路径。
+- 还有个死结记在这里：令牌不能指向**还不存在**的包（会报
+  `You do not have access to the requested package(s)`），所以**第一版只能用浏览器验证发**，
+  令牌是「包已经存在之后」才有的便利。
+
+
+插件没有 GUI 外壳，配置入口是插件注册在 `webServer` 上的**仅限本机访问**（`localOnly` 守卫）
+的 HTTP 端点。`host.js` 启动后，其 `webServer.port` 就是下面 URL 里的 `<port>`
+（无头部署下固定 `3080`）：
+
+```sh
+curl http://127.0.0.1:<port>/api/relay/status     # 实例 ID、连接地址、开关状态
+curl http://127.0.0.1:<port>/api/relay/pairing    # 配对码 + 可直接扫码的 SVG 二维码
+```
+
+- `POST /api/relay/toggle` body `{"enabled":true|false}` —— 开关远程控制
+- `POST /api/relay/regenerate` —— 轮换配对码
+- `POST /api/relay/config` —— 改写 `relayUrl` / `lanEnabled` / `lanPort` / `name` / `pairingPolicy`（无 GUI 外壳时唯一的配置入口）
+- `POST /api/relay/reconnect` —— 重新握手隧道与局域网代理
+
+持久化配置在 `mobile-remote-control` 设置命名空间：`enabled`（默认 `false`）、`relayUrl`
+（默认空，即只用局域网）、`lanEnabled`（默认 `true`）、`lanPort`（默认 `18787`）、`name`。
+插件启动后**不向控制台打印配对信息**，只能经上述端点获取。
+
+## 自动归档
+
+插件默认启用 Host 侧自动归档：激活时扫描一次，此后每 12 小时扫描一次；项目内会话数超过 10 且最后更新时间超过 24 小时的非运行、非空白会话会被归档。归档只隐藏会话，不删除日志。
+
+## 会话清理工具
+
+插件注册模型工具 `session_cleanup`，可直接通过对话执行归档或永久删除。`action: "archive"` 按项目路径、闲置分钟数或会话 ID 筛选并隐藏会话；`action: "delete"` 只处理已经归档的会话，并且必须显式传入 `confirm: true`，删除会话日志和本地投影缓存。删除不可恢复，运行中、空白会话默认不会处理。
+
+## 远程控制元数据
+
+配对请求（relay 的 `pairRequest` 或局域网 `POST /__lan_pair`）可携带 `device` 对象，字段会原样转发并兼容旧版仅传 `code` 的请求。当前 App 发送 `id`、`deviceId`、`name`、`platform`、`osVersion`、`appVersion`，局域网代理与中转会补充服务端观察到的手机 `ip`。
+
+## 配对授权策略
+
+配对码校验始终由传输层完成（中转与局域网代理都用恒定时间比较，且中转对每实例每 IP 做 5 次失败锁定 60 秒）；校验通过后，宿主端由 `pairingPolicy` 决定是否准入，两条链路都汇总到同一个 `POST /api/relay/internal/approval`：
+
+| 取值 | 行为 |
+| --- | --- |
+| `code`（默认） | 凭配对码放行 |
+| `deny` | 拒绝一切新配对 |
+
+原来的桌面端弹窗确认随桌面端一并删除，宿主已无 UI 承接逐次确认，因此改为该策略；`deny` 与删除前的 fail-closed 行为完全等价。策略求值在 [`lib/relay/pairing-policy.js`](lib/relay/pairing-policy.js)，不经过 sidecar worker，故未列入 worker 的 `configure` 白名单。走 `deny` 时每次决策都会写一行审计日志到 stderr。
+
+`/api/mobile/v1/status` 和 `/api/relay/status` 返回宿主 `os`、`osVersion`、`arch`、`appVersion`；移动 token 的签发与校验仍严格绑定宿主 `instanceId`。

package/config/agent-presets/standard/agent.cordis.yml

@@ -0,0 +1,170 @@
+  - id: agent-instructions
+    name: '@deepseek-ai/dsh-agent-instructions'
+    config:
+      maxBytes: 65536
+  - id: tool-bash
+    name: '@deepseek-ai/dsh-tool-bash'
+    disabled: !!js process.platform === 'win32'
+  - id: tool-pwsh
+    name: '@deepseek-ai/dsh-tool-pwsh'
+    disabled: !!js process.platform !== 'win32'
+  - id: tool-fs
+    name: '@deepseek-ai/dsh-tool-fs'
+  - id: tool-fs-search
+    name: '@deepseek-ai/dsh-tool-fs-search'
+    config:
+      sampleOverCapGlobResults: false
+  - id: tool-jobs
+    name: '@deepseek-ai/dsh-tool-jobs'
+  - id: skill-filesystem
+    name: '@deepseek-ai/dsh-skill-filesystem'
+  - id: tool-skill
+    name: '@deepseek-ai/dsh-tool-skill'
+  - id: command-goal
+    name: '@deepseek-ai/dsh-command-goal'
+  - id: tool-goal
+    name: '@deepseek-ai/dsh-tool-goal'
+  - id: planning
+    name: cordis:group
+    group: true
+    isolate:
+      planMode: true
+    config:
+      - id: plan-mode
+        name: '@deepseek-ai/dsh-plan-mode'
+        config:
+          section: >
+            You are in plan mode. Stay in plan mode until exit_plan_mode
+            succeeds or the user switches the session mode. Imperative
+            language to implement changes means plan the implementation, not
+            execute it. A user's conversational agreement — including an
+            answer confirming something you asked — approves nothing and
+            does not end plan mode; fold the confirmed decision into the
+            plan and submit it through exit_plan_mode.
+
+
+            Explore first. Use non-mutating reads, searches, static
+            analysis, and checks to ground the plan in the actual
+            repository. Do not edit or write files, change configuration,
+            run formatters or code generation that rewrites tracked files,
+            commit, or otherwise carry out the plan. Prefer existing
+            functions and patterns over new machinery.
+
+
+            The tool catalog stays the same across modes for request-cache
+            stability. These plan-mode rules override any later tool
+            description or guidance that suggests using mutation tools;
+            those tools remain listed to keep the tool catalog unchanged. Do
+            not use todo_write to track this planning phase: it tracks
+            implementation after an approved plan, while the plan itself
+            belongs in exit_plan_mode.
+
+
+            Resolve discoverable facts by inspection. Use ask_user_question
+            only for user-owned choices or material ambiguity that
+            inspection cannot answer. Do not ask the user where code lives
+            or how current behavior works when you can find out.
+
+
+            Make the plan decision-complete: state the goal and success
+            criteria; group implementation changes by subsystem; identify
+            public API, schema, and data-flow changes; cover edge cases,
+            failure modes, tests, acceptance criteria, and explicit
+            assumptions. Keep it concise enough to review but detailed
+            enough that another engineer can implement it without making
+            design decisions.
+
+
+            When ready, call exit_plan_mode with the complete plan markdown,
+            starting with a # title. Make exit_plan_mode the only and final
+            tool call in that assistant response: it presents the plan for
+            approval, and implementation begins only in a later step after
+            approval. Do not paste the final plan as a plain reply or ask
+            "should I proceed?" through prose or ask_user_question. If
+            review rejects it, incorporate the feedback and present again.
+            If the review channel is unavailable or aborted, stay in plan
+            mode and ask the user to switch modes manually; do not proceed
+            with implementation.
+  - id: compaction
+    name: cordis:group
+    group: true
+    isolate:
+      compaction: true
+      toolResultPruner: true
+    config:
+      - id: compaction-basic
+        name: '@deepseek-ai/dsh-compaction-basic'
+      - id: command-compact
+        name: '@deepseek-ai/dsh-command-compact'
+      - id: tool-result-pruner
+        name: '@deepseek-ai/dsh-compaction-tool-result-pruner'
+        config:
+          thresholdChars: 8192
+          headChars: 4096
+          tailChars: 1024
+  - id: delegation
+    name: cordis:group
+    group: true
+    isolate:
+      workflowEngine: true
+    config:
+      - id: tool-subagent-control
+        name: '@deepseek-ai/dsh-tool-subagent-control'
+      - id: tool-subagent-list-agents
+        name: '@deepseek-ai/dsh-tool-subagent-control/list-agents'
+      - id: tool-subagent
+        name: '@deepseek-ai/dsh-tool-subagent'
+        config:
+          provider: spawn
+          toolName: subagent
+          modelSelectionSettings: true
+          backgroundMode: continuable
+      - id: tool-subagent-fork
+        name: '@deepseek-ai/dsh-tool-subagent'
+        config:
+          provider: fork
+          toolName: subagent_fork
+          backgroundMode: continuable
+      - id: tool-subagent-codex
+        name: '@deepseek-ai/dsh-tool-subagent'
+        disabled: true
+        config:
+          provider: codex
+          toolName: subagent_codex
+          backgroundMode: one-shot
+          maxDepth: provider-managed
+      - id: tool-subagent-claude-code
+        name: '@deepseek-ai/dsh-tool-subagent'
+        disabled: true
+        config:
+          provider: claude-code
+          toolName: subagent_claude_code
+          backgroundMode: one-shot
+          maxDepth: provider-managed
+      # `tool-workflow` is deliberately absent: it injects `workflowEngine`,
+      # which only `@deepseek-ai/dsh-workflow-ptc` provides, and that package
+      # has no 0.1.1-rc.2 release (its earliest is 0.1.6-alpha.1). The App's
+      # workflow surfaces therefore have nothing to run on this host.
+      - id: tool-ralph
+        name: '@deepseek-ai/dsh-tool-ralph'
+        disabled: true
+        config:
+          subagentProvider: spawn
+          maxRounds: 64
+  - id: tool-todo
+    name: '@deepseek-ai/dsh-tool-todo'
+    config:
+      allowParallelInProgress: true
+  - id: tool-web
+    name: '@deepseek-ai/dsh-tool-web'
+    config:
+      fetch: true
+      searchTimeoutMs: 60000
+  # Without this row the mobile host's tool catalog has no `ask_user_question`,
+  # so the App's question dock could never appear: the model simply reports that
+  # the tool is unavailable. `@deepseek-ai/dsh-host-apiproxy` already registers
+  # the `ctx.userQuestions` provider that bridges `ask()` to the mux
+  # `question/requested` frame, and the plugin's `lib/mobile/questions.js`
+  # answers it — only the tool row was missing.
+  - id: tool-ask-user
+    name: '@deepseek-ai/dsh-tool-ask-user'

package/config/agent-presets/standard/preset.yml

@@ -0,0 +1,3 @@
+name: Standard
+description: The standard coding agent: shell, files, search, skills, goals, planning, compaction and delegation.
+order: 1

package/cordis.mobile-host.yml

@@ -0,0 +1,48 @@
+# 只给**无头移动宿主**用的 overlay 层，由 host.js 显式加载（不是 bundle 层）。
+#
+# 为什么单独一个文件：这个包同时有两种宿主，而这一层里的每一行都只对其中一种成立。
+#   - 桌面 GUI：`~/.dsh/profiles/desktop` 通过 DSH 内置插件管理器把本包装成 bundle，
+#     于是 `dsh.bundle.patch`（cordis.patch.yml）会作为一层落到桌面 profile 的树上。
+#     下面 directory-picker 的两行如果留在那一层，桌面的「选择目录」就会从原生
+#     对话框换成 browse —— 桌面自己不需要这个改动（它的操作者就坐在机器前）。
+#   - 无头移动宿主：`host.js` 逐层拼 patch，它想开浏览器/想让手机能选目录，所以才要这些行。
+# 所以「挂载自己」留在 cordis.patch.yml（两种宿主都要），「宿主专属配置」放这里。
+#
+# 行序即优先级：host.js 把它排在 profile 自身的 patch 层之后，所以这里的每一行都
+# 能盖掉更早的层。
+
+# A headless mobile host has no operator waiting for a browser window, so the
+# web runtime must neither open one nor print a URL nobody will read.
+- id: web-runtime
+  config:
+    openBrowser: false
+    printUrl: false
+    surfaceContext: false
+    trustedHosts: []
+
+# 手机是远程客户端，看不到被控端的原生选择框。directory-picker-auto 只在「宿主 web
+# 服务绑定到非 127.0.0.1」时才认为存在远程客户端，从而挂 browse；而移动宿主故意把
+# web 服务留在回环（手机是从 sidecar/中转进来的，不直连宿主的 web 端口，见上面
+# web-runtime 一行），于是它在启动时必定解析成 native —— 手机点「添加工作区」只能看到
+# host.listDirectory needs the browse capability，既列不出目录也建不了目录，只能登记
+# 一个已经存在的路径，「新建工作目录」这条流程从根上就走不通。
+#
+# upstream 那行自己留了出口：「Mount -native or -browse directly in an overlay to pin
+# the interaction.」这里就按它说的把交互钉成 browse：这个宿主存在的意义就是给手机用，
+# 而 browse 后端（dsh-host-directory-picker-browse，纯 node stdlib 实现）不依赖任何
+# 本机显示会话，正是为远程客户端准备的。
+#
+# 注意 patch 的语义（cordis-plugin-include 的 applyEntryPatches）：一行 patch 里的
+# `name` 是「断言」而不是「改写」—— 只有和原行同名才会应用，而且 `name` 本身被排除在
+# 覆盖字段之外。所以想换掉一个插件的挂载，只能先 `disabled: true` 关掉原行，再 insert
+# 一行自己的。直接写 `- id: <原 id>` + 新 `name:` 会被静默跳过（只留一行 loader 警告）。
+#
+# 只 insert 宿主后端、不 insert 客户端界面：移动宿主不开渲染器
+# （web-runtime 的 surfaceContext: false），而且 dsh-client-ui-directory-picker-browse
+# 并不在本包的依赖闭包里（它只嵌在 dsh-web-app 的 node_modules 下），按名字解析不到。
+- id: directory-picker
+  disabled: true
+
+- insert:
+    - id: directory-picker-browse
+      name: '@deepseek-ai/dsh-host-directory-picker-browse'

package/cordis.patch.yml

@@ -0,0 +1,21 @@
+# dsh bundle patch：把移动 API 插进 profile 的层栈。
+#
+# 这一层**两种宿主都会加载**（桌面 GUI 走 DSH 内置插件管理器把它当 bundle；无头宿主
+# 由 host.js 显式作为 overlay 加载），因此这里只放「两种宿主都需要」的行 —— 目前就是
+# 挂载本插件自己这一行。宿主专属的行（不开浏览器、把目录选择器钉成 browse）在
+# cordis.mobile-host.yml，只由 host.js 加载，桌面碰不到。
+#
+# 挂载本插件自己的那一行在这里：`dsh.profile.bundles` 只让这个包的 patch 成为叠加层，
+# 它不会凭空挂载任何东西（没有 insert 行的话，插件装了但永远不会被载入 —— 不报错、
+# 只是没有 /api/mobile/v1，也没有 sidecar）。桌面端装进 `~/.dsh/profiles/desktop` 后
+# 插件就在 profile 的 node_modules 里，按包名解析得到的就是 lib/index.js。
+#
+# 无头宿主 host.js 会**在装载前把这一行摘掉**（见 host.js 的 dropBareNameSelfMounts）：
+# 那个场景下插件不在自己的 node_modules 里，裸名解析不到，而 loader 对解析失败不是
+# 「留一条警告」而是整棵树加载失败（实测 `plugin tree failed to load: failed to import
+# loader entry dsh-mobile (dsh-mobile-plugin): Cannot find package 'dsh-mobile-plugin'`
+# —— 服务器宿主曾因此完全起不来）。host.js 用绝对路径另插一行 `mobile-api`，那才是
+# 无头宿主的挂载点。
+- insert:
+    - id: dsh-mobile
+      name: 'dsh-mobile-plugin'

package/dsh-mobile-credentials/lib/credentials.js

@@ -0,0 +1,135 @@
+'use strict';
+
+/** Persistent per-device relay credentials. The bearer secret is returned once;
+ * only its hash is stored on disk. The host token is retained so a durable
+ * relay credential can continue to authenticate legacy 30-day clients. */
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+
+const FILE = process.env.DEVICE_CREDENTIALS_FILE || path.join(process.env.DSH_HOME || path.join(os.homedir(), '.dsh'), 'relay-device-credentials.json');
+/** Default credential lifetime. `issue(..., ttlMs)` may override; `ttlMs <= 0` opts out. */
+const DEFAULT_TTL_MS = 365 * 24 * 3600 * 1000;
+let loaded = false;
+let records = [];
+function digest(value) { return crypto.createHash('sha256').update(String(value)).digest('hex'); }
+/** Constant-time hash comparison (both sides are 64-char hex). */
+function hashEquals(a, b) {
+  const left = Buffer.from(String(a), 'utf8');
+  const right = Buffer.from(String(b), 'utf8');
+  if (left.length !== right.length) return false;
+  return crypto.timingSafeEqual(left, right);
+}
+function load() {
+  if (loaded) return;
+  loaded = true;
+  try { const data = JSON.parse(fs.readFileSync(FILE, 'utf8')); records = Array.isArray(data) ? data : []; } catch { records = []; }
+}
+function save() {
+  fs.mkdirSync(path.dirname(FILE), { recursive: true });
+  const tmp = `${FILE}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify(records, null, 2), { mode: 0o600 });
+  fs.renameSync(tmp, FILE);
+}
+function issue(instanceId, device, hostToken, ttlMs = DEFAULT_TTL_MS) {
+  load();
+  const deviceId = String(device?.deviceId || device?.id || crypto.randomUUID()).slice(0, 128);
+  const credential = `dshc_${crypto.randomBytes(32).toString('base64url')}`;
+  const now = Date.now();
+  // A host instance may be paired with multiple phone installations.
+  // deviceId is client metadata and can collide after app-data migration or
+  // cloning, so it must not be used as a uniqueness constraint for credentials.
+  const record = { instanceId, deviceId, hash: digest(credential), hostToken: typeof hostToken === 'string' ? hostToken : '', createdAt: now };
+  // `find()` has always honoured `expiresAt`, but nothing ever set it — so every
+  // credential was permanent and "revoke" only marked records that the cookie
+  // path never consulted. Issue an explicit expiry by default.
+  if (Number.isFinite(ttlMs) && ttlMs > 0) record.expiresAt = now + ttlMs;
+  records.push(record);
+  save();
+  return { credential, deviceId, expiresAt: record.expiresAt || null };
+}
+function find(credential, instanceId) {
+  load();
+  if (typeof credential !== 'string' || !credential) return null;
+  const hash = digest(credential);
+  const now = Date.now();
+  let match = null;
+  // Scan every record: an early-exit `Array.find` would leak the matching
+  // position through response timing.
+  for (const record of records) {
+    const same = hashEquals(record.hash, hash);
+    if (same && record.instanceId === instanceId && isLive(record, now)) match = record;
+  }
+  return match;
+}
+/**
+ * Look up a credential this store issued, whether or not it is still live.
+ *
+ * `find()` answers "may this caller proceed?". This answers "did we ever issue
+ * this here?" — and the difference is load-bearing. The desktop host and the
+ * Relay keep separate credential stores, so a phone paired over the public
+ * Relay presents a `dshc_` the host has never seen. That one must fall back to
+ * its stateless token instead of being rejected. A `dshc_` the host *did* issue
+ * must instead be authoritative, so that revoking it takes effect immediately.
+ */
+function lookup(credential, instanceId) {
+  load();
+  if (typeof credential !== 'string' || !credential) return null;
+  const hash = digest(credential);
+  let match = null;
+  for (const record of records) {
+    const same = hashEquals(record.hash, hash);
+    if (same && record.instanceId === instanceId) match = record;
+  }
+  return match;
+}
+/** True when a record is neither revoked nor past its expiry. */
+function isLive(record, now = Date.now()) {
+  return Boolean(record) && !record.revokedAt && (!record.expiresAt || record.expiresAt > now);
+}
+/**
+ * Look up the newest live credential issued to a device.
+ *
+ * Pairing cookies carry a deviceId instead of the bearer secret, so this is the
+ * only way for the Relay to notice that a device was revoked (or that its
+ * credential expired) without the phone having to present the secret itself.
+ */
+function isActiveDevice(instanceId, deviceId) {
+  load();
+  if (typeof deviceId !== 'string' || !deviceId) return null;
+  const now = Date.now();
+  let match = null;
+  for (const record of records) {
+    if (record.instanceId === instanceId && record.deviceId === deviceId && isLive(record, now)) match = record;
+  }
+  return match;
+}
+function revoke(credential, instanceId) {
+  load();
+  const record = find(credential, instanceId);
+  if (!record) return false;
+  record.revokedAt = Date.now();
+  save();
+  return true;
+}
+function listActive() {
+  load();
+  return records.filter((record) => !record.revokedAt && (!record.expiresAt || record.expiresAt > Date.now())).map(({ instanceId, deviceId, createdAt, expiresAt }) => ({ instanceId, deviceId, createdAt, ...(expiresAt ? { expiresAt } : {}) }));
+}
+function revokeDevice(instanceId, deviceId) {
+  load();
+  let count = 0;
+  for (const record of records) if (record.instanceId === instanceId && record.deviceId === deviceId && !record.revokedAt) { record.revokedAt = Date.now(); count += 1; }
+  if (count) save();
+  return count;
+}
+/** Revoke every live credential issued to a host instance (clear-all-authorization). */
+function revokeAllByInstance(instanceId) {
+  load();
+  let count = 0;
+  for (const record of records) if (record.instanceId === instanceId && !record.revokedAt) { record.revokedAt = Date.now(); count += 1; }
+  if (count) save();
+  return count;
+}
+module.exports = { FILE, DEFAULT_TTL_MS, issue, find, lookup, isLive, isActiveDevice, revoke, revokeDevice, revokeAllByInstance, listActive };

package/dsh-mobile-credentials/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "dsh-mobile-credentials",
+  "version": "0.1.0",
+  "private": true,
+  "description": "DSH 移动端共享凭据库：签发/校验/吊销手机端的持久化中转凭据（中转服务器与宿主插件共用）",
+  "main": "lib/credentials.js",
+  "files": [
+    "lib/**/*.js"
+  ],
+  "engines": {
+    "node": ">= 20"
+  }
+}