device-center 0.0.0-stage → 0.2.0-beta.1

package/CONTRIBUTING.md

@@ -0,0 +1,9 @@
+# Contributing
+
+Source distributed in the npm beta package is licensed under MIT (see LICENSE). The GitHub repository publication plan and a private security reporting channel are still pending. This remains a prototype, not an audited remote execution system.
+
+Use Node.js 24, `npm run dev`, `npm run check`, and `npm test`. There is no third-party runtime dependency or frontend build step. Native inventory includes the real local Driver by default, with no seeded records. SSH references require explicit user selection. Test fixtures must stay in temporary test directories/databases, never appear in product startup.
+
+Preserve the compact sidebar, optional MCP setup, truthful device states, and separate memory/disk observations. The local process represents its machine; a container cannot claim its host. SSH configuration discovery must not execute commands or read keys, and association must not imply connectivity or task authority. Do not restore sample projects, hosted quota displays or simulated cloud synchronization.
+
+Never add real secrets to prompts, packages, fixture data or logs. SSH observation is an explicit owner action using a fixed script, isolated configuration, existing authentication and strict host trust; GET and MCP must never trigger connections. Tests inject subprocess results and do not contact real hosts. Resource enrollment, Agent installation, network discovery, tunnels, cloud deployment and remote tasks require separately scoped implementation and review. Do not run service installation or Docker deployment merely to validate a UI change. Keep user data and unrelated services intact.

package/Dockerfile

@@ -0,0 +1,10 @@
+# Optional local-only control plane, not a host/resource Agent.
+FROM node:24-bookworm-slim
+WORKDIR /app
+COPY --chown=node:node package.json npm-shrinkwrap.json index.html login.html ./
+COPY --chown=node:node server ./server
+COPY --chown=node:node src ./src
+RUN npm ci --omit=dev --ignore-scripts --no-audit --no-fund && mkdir -p /app/data && chown node:node /app/data
+USER node
+ENV PORT=5173 DEVICE_CENTER_RUNTIME=container DEVICE_CENTER_DB_PATH=/app/data/device-center.sqlite
+CMD ["node", "server/index.mjs"]

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 owenshen0907
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,63 @@
-# Temporary Holding Version
+# Device Center
 
-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.
+让主力电脑上的智能体，使用自己的闲置设备。MIT · Node.js 24 · macOS / Linux · beta。
+
+一个本机连接器，加一个可选的云端控制面。真实本机内存、磁盘分别展示；已有 SSH 配置可一键关联并执行固定只读检查；设备 Agent 可通过域名绑定账号，主动回报状态。指定日志经设备主人单独授权后，以双向 TLS 1.3 直连或密文中转读取。没有默认示例设备或虚构在线状态。
+
+## 快速使用
+
+只用本机，不注册账号：
+
+```sh
+npx --yes device-center@0.2.0-beta.1 start
+```
+
+打开 `http://127.0.0.1:5174`，将 `/mcp` 添加到本机智能体。侧栏“开始使用”按管理电脑 → 智能体 → 设备引导；导入 SSH 后检查一次连通性。没有可用 Agent/SSH 的设备保持未知；资源快照过期显示“待刷新”，不代表密钥过期。列表刷新不主动连接 SSH。
+
+需要在外查看设备、使用日志中转：
+
+```sh
+npx --yes device-center@0.2.0-beta.1 plan
+npx --yes device-center@0.2.0-beta.1 connect --confirm
+# 自建控制面可指定 --cloud https://devices.example.com
+```
+
+默认 [官方控制面](https://devices.owenshen.top)，登录自己的 App Services／个人站统一账号。在面板输入终端的五分钟配对码，核对完整公钥指纹和回报范围并批准。私钥留在设备，不放进脚本、prompt 或压缩包。默认不分享 SSH 信息、不开 LAN 端口、不安装后台服务。配对只授权资源回报。
+
+[远程日志：两端授权、直连与中转](docs/remote-access.md) · [常驻与 npm](docs/npm.md) · [账号模式与自建](docs/hosted-access.md) · [故障排查](docs/troubleshooting.md)
+
+## 能做什么
+
+| 能力 | 当前实现 |
+| --- | --- |
+| 资源清单 | 本机真实资源；已有 SSH 主机经用户触发检查；云端只显示获准回报 |
+| 账号与设备 | 上游核验账号、租户隔离、短期一次性批准、签名防重放、撤销 |
+| 日志 | 指定标签/绝对文件/管理设备/有效期，最大64KiB；本机审计 |
+| 访问路径 | Agent 精确私网入口优先，网络失败回退官方/自建 HTTPS 密文中转；证书错误停止 |
+| 中转额度 | 每账号100MiB/UTC日、全实例1GiB/日，持久计数、并发与速率限制 |
+| 尚未提供 | 任意远程命令、通用文件传输、Windows 原生 Agent、云端 MCP、CF 专用适配器、计费、自动迁移 |
+
+日志操作通过 `device_center_read_log` 请求，不能用 MCP 授权自身。用户自己的智能体仍需在目标设备单独配置授权。已有 SSH 路径独立使用，SSH“连接计划”不会自动改成新 Agent 通道。Docker 代表容器自身，不能当作宿主机；宿主运行原生 Driver 与本机智能体交互。
+
+## 从源码运行和自建
+
+```sh
+npm ci --ignore-scripts
+npm run dev
+# 默认 http://127.0.0.1:5173
+npm run check
+npm test
+npm run verify:package
+```
+
+无前端构建步骤；依赖由 npm-shrinkwrap 固定。仅本机模式监听回环地址，不可直接公开。可选 `docker compose up --build -d` 使用本地回环端口映射与非 root 用户，未挂载宿主 HOME/SSH/Docker socket。容器不能代替用户本机 Driver。
+
+云端部署必须设置 `DEVICE_CENTER_RUNTIME=cloud`、`DEVICE_CENTER_PUBLIC_ORIGIN=https://你的域名`、`DEVICE_CENTER_AUTH_FILE=/仓库外/private.json`。已有反向代理仅转发至服务回环端口，覆盖 Host 和 X-Forwarded-Proto，提供 HTTPS。认证配置文件0600：
+
+```json
+{"provider":"app-services","accountMode":"multi-user","backendOrigin":"https://appapi.example.com","accountOrigin":"https://example.com"}
+```
+
+需要已有受信任 App Services 共享账号服务与同父域会话；不是通用第三方 OAuth。个人部署可选 personal + ownerEmail。旧个人数据切多用户前按[迁移与回退说明](docs/hosted-access.md)核验原所有者映射；不能只切回旧代码而保留多用户数据库。
+
+当前没有密钥托管、安装时自动联网或远程 shell。安全边界与披露方式见 [SECURITY](SECURITY.md)。npm 包公开不自动改变 GitHub 仓库可见性；本次发布是可追溯工作区快照，不是 main CI 构建。

package/SECURITY.md

@@ -0,0 +1,15 @@
+# Security
+
+Device Center 0.2.0-beta.1 is a beta for macOS/Linux and Node.js 24. Local HTTP/MCP is loopback-only with Host/Origin checks; do not expose it publicly. Cloud deployment requires an exact HTTPS origin, a proxy overwriting Host/scheme, and a private authentication config. App Services identities are verified against the configured upstream; tenant scope comes from verified stable issuer/subject. Authentication outages fail closed.
+
+Device keys remain in owner-private local files. Pairing is short-lived, one-time and separately approved after a full fingerprint comparison. Binding permits telemetry, not operations. Remote log access requires local pinned peer certificates plus a target-owned file/label/expiry grant. Node/OpenSSL TLS 1.3 mutually authenticates both devices over an approved LAN endpoint or opaque HTTPS relay; certificate and hostname verification remain enabled. The control plane sees metadata and ciphertext, not log plaintext or private keys. First-use fingerprint verification requires a trusted channel.
+
+Only bounded log tail reads are available. No arbitrary commands, generic file transfer, Windows native Agent or cloud MCP. Symlink/multiple-hardlink/non-regular log files are rejected. Cloud revocation is checked on both routes. Local audit is bounded and fails closed at capacity. OS administrators, compromised endpoints and already-authorized readers remain trust boundaries. Keys are not TPM/Keychain wrapped. See [permissions, quotas, certificate renewal and limitations](docs/remote-access.md).
+
+Telemetry inventory never initiates SSH. Explicit local checks use bounded fixed scripts and strict known-host verification; private-key contents and raw SSH output are not imported. Containers do not read host SSH or claim host metrics.
+
+Multi-user rollback requires consistent database and private-config restoration; never activate an older unscoped server against multi-account data. See [migration](docs/hosted-access.md). This release has automated isolation/transport tests, not an independent security audit or SLA.
+
+## Report a vulnerability
+
+Do not post private keys, enrollment codes, cookies, logs or live credentials publicly. Contact the maintainer through a private channel before sharing sensitive details. The repository may be private even while the MIT npm package is public; no public issue tracker or bounty is promised. Stop recommending an affected beta and issue a new version rather than overwriting a published artifact.

package/bin/device-center.mjs

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+import { readFileSync, realpathSync } from 'node:fs';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const ROOT = fileURLToPath(new URL('..', import.meta.url));
+const version = () => JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
+export function parseCli(argv = []) {
+  const command = argv[0] ?? 'help';
+  if (['help', '--help', '-h', '--version', '-v'].includes(command)) {
+    if (argv.length > 1) throw new Error('帮助和版本命令不接受其他参数。');
+    return { command: command === '-v' ? '--version' : ['-h', '--help'].includes(command) ? 'help' : command };
+  }
+  if (!['start', 'plan', 'connect', 'run', 'status', 'disconnect', 'service', 'access'].includes(command)) throw new Error('未知命令。运行 device-center --help 查看用法。');
+  const args = argv.slice(1);
+  if (command === 'start') {
+    let port = 5174;
+    if (args.length) {
+      if (args.length !== 2 || args[0] !== '--port') throw new Error('用法：device-center start [--port 5174]');
+      port = Number(args[1]);
+    }
+    if (!Number.isInteger(port) || port < 1024 || port > 65535) throw new Error('端口须为 1024 到 65535。');
+    return { command, port };
+  }
+  if (command === 'service') {
+    if (!['plan', 'status', 'install', 'uninstall'].includes(args[0] ?? 'plan')) throw new Error('用法：device-center service plan|status|install|uninstall [--port 5174] [--confirm]');
+    return { command, args: args.includes('--port') ? args : [...(args.length ? args : ['plan']), '--port', '5174'] };
+  }
+  return { command, args };
+}
+export function helpText() {
+  return `Device Center ${version()} · 只读管理 Driver 源码原型
+
+需要 Node.js 24；管理 Driver 支持 macOS / Linux。
+
+device-center start [--port 5174]             启动本机面板与只读 MCP
+device-center plan --cloud https://你的域名    预览回报范围，不生成身份或联网
+device-center connect --cloud https://你的域名 --confirm
+                                            在本机生成身份，申请配对后等待你核对批准
+device-center status                         查看已有绑定，不显示私钥
+device-center run [--port 5174]               前台恢复已绑定 Driver
+device-center disconnect --confirm           通知云端撤销，保留本机身份
+device-center service plan|status|install|uninstall [--port 5174] [--confirm]
+
+默认端口5174，数据位于本用户的应用数据目录。关闭网页不会停止前台进程。
+默认回报本机名称、系统、内存和磁盘；--share-ssh 需命令申请及面板另行批准。
+本机无需平台注册；connect 默认申请接入 https://devices.owenshen.top，需登录自己的账号核对批准。
+--cloud 可使用自建域名。device-center access help 查看受限日志授权与可选局域网直连。
+支持 TLS 1.3 双向认证的日志读取与密文中转，默认100MiB/账号/日；不会自动获得操作权限。
+任意远程命令、通用文件传输和 Windows 原生 Driver 尚未提供。安装包不含身份或配对码。
+使用 npx 时只运行前台；常驻请先将本包固定版本安装到长期目录，再单独 install。
+`;
+}
+export async function main(argv = process.argv.slice(2)) {
+  const plan = parseCli(argv);
+  if (plan.command === 'help') return helpText();
+  if (plan.command === '--version') return version();
+  if (Number(process.versions.node.split('.')[0]) < 24) throw new Error('需要 Node.js 24 或更高版本。');
+  if (plan.command === 'access') return (await import('../scripts/access.mjs')).main(plan.args);
+  if (plan.command === 'service') {
+    if (plan.args[0] === 'install' && /(?:^|[\\/])_npx[\\/]/.test(ROOT)) throw new Error('npx 缓存会被清理，不能用作常驻目录。请先 npm install -g device-center@固定版本，再运行 device-center service install --confirm。');
+    return (await import('../scripts/service.mjs')).main(plan.args);
+  }
+  const driver = await import('../scripts/driver.mjs');
+  if (plan.command === 'start') {
+    if (process.platform === 'win32') throw new Error('Windows 原生管理 Driver 尚未支持。');
+    await driver.runLocal({ port: plan.port }); return;
+  }
+  return driver.main([plan.command, ...plan.args]);
+}
+// npm links bin entries through a symlink; compare the actual script, not the link path.
+if (process.argv[1] && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href) {
+  try {
+    const result = await main();
+    if (result != null) console.log(typeof result === 'string' ? result : JSON.stringify(result, null, 2));
+  } catch (error) { console.error(error.message); process.exitCode = 1; }
+}

package/compose.yaml

@@ -0,0 +1,22 @@
+services:
+  device-center:
+    build: .
+    ports:
+      - "127.0.0.1:${DEVICE_CENTER_PORT:-5173}:5173"
+    environment:
+      DEVICE_CENTER_SERVICE_MANAGER: docker
+    volumes:
+      - device-center-data:/app/data
+    restart: unless-stopped
+    init: true
+    security_opt:
+      - no-new-privileges:true
+    cap_drop:
+      - ALL
+    healthcheck:
+      test: ["CMD", "node", "--input-type=module", "-e", "const r = await fetch('http://127.0.0.1:5173/api/health'); process.exit(r.ok ? 0 : 1)"]
+      interval: 30s
+      timeout: 5s
+      retries: 3
+volumes:
+  device-center-data:

package/docs/architecture.md

@@ -0,0 +1,34 @@
+# 架构
+
+Device Center 是模块化 Node.js 单体，前端静态文件无构建步骤。Node.js 24 内置 SQLite，Node/OpenSSL 提供 TLS；@peculiar/x509 创建标准证书，依赖由 npm-shrinkwrap 固定。
+
+## 两个运行位置
+
+- 本机 Driver：本机真实资源、已有 SSH 别名引用和缓存、回环 HTTP 面板/MCP；原生模式可显式绑定控制面，运行资源 Publisher 与获准日志 Agent。容器只代表自身。
+- 云端控制面：统一账号鉴权、账号隔离的设备登记/回报/撤销、密文 Relay。不会读取服务器 SSH 或把服务器伪装成管理电脑；没有云端远程 shell/MCP。
+
+```mermaid
+flowchart LR
+  AI[本机智能体] --> MCP[回环 MCP / 管理 Driver]
+  MCP -->|获准精确 LAN 地址 · 双向 TLS| Target[目标 Driver · 日志授权]
+  MCP -->|TLS 密文 / 签名 HTTPS| Relay[官方或自建控制面]
+  Relay -->|目标主动取帧| Target
+  Target -->|签名指标回报| Relay
+```
+
+## 模块
+
+| 模块 | 职责 |
+| --- | --- |
+| index / cloudAccess / unifiedAccess | 本机请求边界、HTTPS代理验证、固定上游账号核验、会话 |
+| inventory / sshConfig / sshProbe / sshRoute | 被动解析 SSH 元数据、显式只读检查、独立指标和核验路径 |
+| driverProtocol / cloudRegistry | Ed25519 签名上下文、持久防重放、一次性配对、租户归属与资源时效 |
+| certificates | 同设备身份的 X509 创建、指纹与自签验证 |
+| relay | 有界密文帧队列、成员与撤销验证、持久日额度 |
+| access / remote | 本机指纹信任、单文件限时授权、日志尾读、审计、标准双向 TLS、直连及回退 |
+| connector | 四个本机只读工具，另有同账号设备查询和获准日志读取，共六个工具 |
+| scripts/driver / access / service | 显式绑定、端上授权、用户级常驻；不会在 npm 安装钩子中运行 |
+
+两条路径使用同一证书身份和端上授权。云端登记不授予日志权限；peer目录不能替换本机核对过的指纹。只有网络不可达可回退，认证错误停止。现有 SSH 设备的“连接计划”仍只保存元数据，与 Agent 通道分离。
+
+TLS 记录分片经签名 HTTPS 请求转发，不自行设计密码协议。会话60秒，队列有上限；连接失败后不恢复/重放操作。当前仅只读日志，没有通用任务系统。参见[完整协议边界](remote-access.md)。

package/docs/connection-routing.md

@@ -0,0 +1,66 @@
+# 访问路径与局域网优先
+
+> 0.2.0-beta.1 更新：账号隔离、TLS 1.3 双向认证密文中转、独立授权的日志尾读及获准精确 LAN 优先已实现。旧文中的“尚未实现”传输描述属于此前阶段；实际操作与边界以 [远程日志](remote-access.md) 和 README 为准。通用远程命令、文件传输、Windows 原生 Agent 与自动迁移仍未提供。
+## 当前能做什么
+
+面板的每台设备显示配置路径，点击路径可查看节点、地址和端口。MCP 库存读取同一份信息。原生本机由进程直接采集；SSH 设备的路径来自保守解析并用于检查的配置，读取与展示时不调用 `ssh -G`、不解析动态命令、不探测 DNS 或网络。导入后一次检查、或用户手动重试，才实际访问已配置路径。
+
+- `ssh.route`：当前经过核验的配置路径；包含目标和跳板的别名、地址、端口、地址类别，不含登录用户名、身份文件引用或私钥内容。
+- `ssh.lastVerifiedRoute`：仅当成功检查的配置摘要仍与当前相同，才给出该检查的时间和路径。配置改变时旧快照失效，不能把新路径冒充上次用过的路径。
+- `selection: configured-only`、`liveConnection: false`：当前固定按配置访问，没有自动选路或常驻连接。
+- 地址类别只依据字面值。私网地址不证明同一局域网、可达性或主机身份；主机名未解析，其他 IP 不声明一定是公网。
+
+快照超过五分钟的内部状态仍为 `expired`，面板显示“待刷新”。它表示内存/磁盘数据较早，不表示 SSH 密钥过期或设备断线。刷新列表不重连；导入后检查一次，后续点“检查 SSH（只读）”才重新采集。
+
+## 跳板为什么能访问设备
+
+```mermaid
+flowchart TD
+  Local[本机 SSH 客户端\n使用本机已有身份] --> Jump[已配置的 SSH 跳板\n转发 TCP 流量]
+  Jump --> Entry[目标 HostName 与端口\n若为回环地址，属于跳板端]
+  Entry -.既有链路，机制未核验.-> Target[目标设备 SSH 服务]
+  Local -.校验跳板和目标身份，分别认证.-> Target
+```
+
+SSH `ProxyJump` 先连接跳板，再从跳板建立到目标入口的转发。目标 SSH 的认证仍由本机客户端完成；无需把目标客户端私钥复制到跳板。目标的 `authorized_keys` 保存允许登录的客户端公钥，公钥不能代替私钥登录。设备、跳板也各自有用于证明服务器身份的主机密钥，不能与用户的登录密钥混为一谈。
+
+若目标入口是跳板上的回环端口，它可能由既有反向转发或其他映射提供。仅凭本机配置与一次成功检查，无法确认后段由谁建立、其具体部署方式或密钥放在哪里。界面对此使用虚线节点并标为未核验；不把推测画成事实。
+
+参考：[OpenSSH ProxyJump](https://man.openbsd.org/ssh_config#ProxyJump)、[HostKeyAlias](https://man.openbsd.org/ssh_config#HostKeyAlias)。
+
+## 下一步实现：已知入口的认证直连与回退
+
+以下是方案，当前不执行。
+
+1. **设备与线路分开登记。** 一个稳定设备记录可以有“已批准的 LAN 入口”和“已批准的云端跳板入口”，避免同一电脑因两个别名变成两台。初次关联由用户确认，不凭别名、hostname 或相同登录私钥自动合并。
+2. **先绑定同一主机身份。** 通过可信渠道核对目标的主机公钥或指纹，把两条路径绑定到同一身份。保留原有严格验钥；按核验结果使用受限 known_hosts / HostKeyAlias 方案。不能仅填写同一个 HostKeyAlias 就宣称身份验证完成，不从云端下载私钥。
+3. **按需尝试获准入口。** 在资源检查或已授权操作开始时，最多尝试明确登记的 LAN 端点，以短超时完成 SSH 主机校验与客户端认证。不开新端口、不枚举网段、不探测未知地址。TCP 能连不代表认证成功。
+4. **选择与回退。** 认证直连成功则使用该连接；连接超时、拒绝或网络不可达，才可回退已经获准的跳板入口。未知/变化的主机身份、认证失败、配置错误和权限问题停止并提示，不用回退隐藏问题。
+5. **对用户解释结果。** 显示实际选中的线路、验证时间、有限的握手耗时及回退原因。局域网优先是策略，不宣称它总有最高吞吐；当前没有速度或带宽测量。网络变化时短期缓存失效，下次按需验证。
+6. **固定一次任务的连接。** 大文件传输沿选定连接传输，不在中途静默换路。失败返回已完成进度；只有经过验证的续传协议才能继续。安装、构建等操作不能自动重放；连接可达不授予操作权限。
+7. **接入智能体操作。** 智能体通过连接器请求范围明确的日志/文件/任务能力，由本机 Driver 使用同一个选路器和认证边界。智能体自行执行原 SSH 别名仍按原配置走，不会因面板出现路径图而自动优化。
+
+验收应覆盖：同一已批准设备直连成功、不在家时回退、无可达线路、身份变化拒绝、认证失败不回退、局域网地址变化需复核，以及传输中断不重放。使用受控夹具与已授权目标分别验证，不用模拟结果宣称真实网络已打通。
+
+当前缺少两台目标的准确局域网入口及同设备身份绑定；“同一局域网”本身不足以补全地址。既有 SSH 检查、路径展示和只读 MCP 可用；自动选路、文件传输和远程任务尚未实现。
+
+## 每台设备的两种连接方式
+
+已关联的 SSH 设备可以同时保存局域网入口和中转方案，界面不再将不同线路登记成不同设备。当前仍以已关联主 SSH 别名作为本地记录键，不将它冒充硬件唯一身份。
+
+| 连接方式 | 配置与用途 | 当前状态 |
+| --- | --- | --- |
+| 局域网直连 | 明确设备地址、SSH 端口；在家优先使用 | 可以保存入口，未认证或探测；显示待验证 |
+| 中转：用户自建服务器 | 用户自己拥有的 VPS / 服务器 | 可保存方案；既有 SSH 跳板仍沿原配置使用；新中继适配器未接入 |
+| 中转：Device Center 服务 | 项目运营方提供的托管服务 | 可保存选择；没有部署服务、分配额度或托管凭据 |
+| 中转：Cloudflare | 用户选择 Cloudflare Tunnel / Access 接入 | 可保存选择；没有注册账号、安装 cloudflared 或建立隧道 |
+
+连接策略可保存为 `lan-first`（局域网优先、中转备用）或 `relay-only`。这些是计划，`effective: false`，不会因保存而启用自动连接，也不会改变已有 SSH 检查、资源状态或权限。服务停止后重启仍可读取本机配置；MCP 只读同一计划，没有写入工具。
+
+`POST /api/devices/ssh/connections` 必须有明确同源 Origin、JSON，并指向当前用户已关联的别名。只接受别名、设备地址、端口、中转类型和连接策略；写入 SQLite 的 `ssh_connection_plans`。地址不接受 URL、用户名、命令或回环入口；端口为 1–65535。计划不含私钥、令牌、登录口令或新增认证权限，字段超出范围会拒绝。空地址或空中转选择可以保存，用于清空这些计划字段；不删除设备或 SSH 配置。
+
+### Cloudflare 的接入条件
+
+Cloudflare 的客户端 `cloudflared` SSH 模式需要在能访问目标 SSH 的设备侧运行隧道连接器，并在管理端配置客户端和 Access 身份策略。也可以另行选择 Cloudflare One 客户端的私网接入模式。不能把它视为无需客户端的通用 SSH 中继，不能承诺所有传输免费或不限量。
+
+参考：[客户端 cloudflared SSH 接入](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/use-cases/ssh/ssh-cloudflared-authentication/)、[Cloudflare One SSH 接入](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/use-cases/ssh/ssh-infrastructure-access/)。当前保守 SSH 检查不执行任意 `ProxyCommand`，Cloudflare 需要独立、范围明确的适配器；选择该方案不会绕过这条边界。

package/docs/driver-binding.md

@@ -0,0 +1,69 @@
+# 通过域名连接管理电脑
+
+> 0.2.0-beta.1 更新：账号隔离、TLS 1.3 双向认证密文中转、独立授权的日志尾读及获准精确 LAN 优先已实现。旧文中的“尚未实现”传输描述属于此前阶段；实际操作与边界以 [远程日志](remote-access.md) 和 README 为准。通用远程命令、文件传输、Windows 原生 Agent 与自动迁移仍未提供。
+当前支持个人控制面与 macOS / Linux 管理 Driver 的配对、只读资源回报和撤销。它不是远程终端或隧道；Windows Driver、独立安装器、系统钥匙串封装、远程任务和自动选路仍待实现。
+
+## 三步接入
+
+1. 登录自己的 HTTPS 控制面，点 **连接我的电脑**。下载 Driver 源码包，在管理电脑解压到长期保留的目录；需要 Node.js 24，无第三方运行依赖。已有最新版源码仓库可直接使用。
+2. 在该目录的终端运行面板复制的命令。下面是占位域名，请替换为自己的 HTTPS 域名。npm 分发候选见 [npm 使用与发布说明](npm.md)：
+
+   ```sh
+   npm run driver -- plan --cloud https://control.example.com
+   npm run driver -- connect --cloud https://control.example.com --confirm
+   ```
+
+   `plan` 不生成身份、不写文件、不联网。`connect --confirm` 在本机生成 Ed25519 身份，并请求五分钟有效的配对码。终端显示配对码和完整公钥指纹，保持终端打开。
+3. 回到控制面，单独输入配对码，核对电脑名称、系统以及与终端一致的完整指纹，再点 **核对一致，绑定这台电脑**。只批准自己刚在手边电脑发起的请求。批准之前不回报资源；批准后等待首次回报，面板才由未知转为在线。
+
+命令和源码包不含配对码、长期凭据、私钥或本机配置。配对码只在本机终端与认证后的面板交互中使用，不交给智能体，不放入 URL、脚本、压缩包或诊断日志。终端显示属于必要交互，请勿录制或转发这一段。
+
+默认回报本机名称、系统类型、内存、用户目录所在卷磁盘及观测时间。需要分享已有 SSH 清单时，在命令中显式增加 `--share-ssh`，面板还需另行勾选批准；至多分享 15 个已关联 SSH 主机的名称和缓存资源状态，不含地址、用户名、路径、配置、原始错误或 SSH 私钥。云端不会要求管理电脑自动检查 SSH。
+
+## 本机使用与常驻
+
+批准后命令会启动回环地址上的前台 Driver，默认端口 5174。保持终端打开，访问 `http://127.0.0.1:5174`，在那里连接本机智能体、导入已有 SSH，并按需检查。云端不读取服务器 SSH，也不能读取浏览器电脑的文件。
+
+已有新版原生 Driver 在相同端口运行时复用它；不会结束旧进程。端口占用时改用 `--port`，MCP 地址与服务安装端口保持一致。
+
+```sh
+npm run driver -- status
+npm run driver -- run --port 5174
+```
+
+前台退出后，可自行重新 `run`。若要登录系统后常驻，先停止自己的前台进程，再执行：
+
+```sh
+npm run service -- plan --port 5174
+npm run service -- install --confirm --port 5174
+```
+
+服务安装是另一个显式操作。它使用独立持久数据库，不自动搬运开发预览数据库；在该本机面板重新导入 SSH 引用。macOS / Linux 用户服务安装脚本已有，实际安装仍需用户执行并在目标系统验证。
+
+身份文件：macOS 为 `~/Library/Application Support/Device Center/driver-link.json`；Linux 为 `~/.local/share/device-center/driver-link.json`。父目录要求 0700、文件 0600、当前用户所有，不接受符号链接或多硬链接身份文件。私钥目前是本机私有文件，并非 Keychain / TPM，不防护已控制本用户的恶意程序。不要上传、共享或直接编辑该文件。
+
+## 状态、断开与排查
+
+- Driver 每约 30 秒主动向固定 HTTPS 域名 POST 回报，面板约 15 秒刷新。无需开放管理电脑的入站端口。网络失败退避至最多五分钟，恢复后自动重试。
+- 未回报为未知；管理电脑最后回报超过 90 秒，或 SSH 缓存超过五分钟，显示待刷新。旧 SSH 观测时间不会被重复回报刷新；管理电脑失联后，其 SSH 快照也标为待刷新。
+- 面板的 **管理连接 → 撤销 → 确认撤销** 会拒绝后续回报。本机看到撤销会禁用回报；不会删除身份文件、SSH 配置或设备记录。
+- 本机主动断开：`npm run driver -- disconnect --confirm`。需要网络可达来通知云端；失败时先在云端撤销。身份文件保留，可再次向同一控制面申请配对。更换控制面不能自动覆盖已有身份。
+- 无请求：检查运行目录、Node 版本、域名 DNS、可信 HTTPS、出站网络；不关闭证书校验。
+- 码失效或已用：在本机重新 `connect`，勿重复批准旧请求。批准成功但本机未及时取得结果时，先撤销那条等待回报的登记，再重新配对。
+- 签名时钟异常：校准系统时间；客户端与服务端偏差大于 90 秒拒绝请求。
+- 私有文件错误：检查所属用户、目录和文件权限；不要输出文件内容到日志或工单。此原型不会自动修复权限、重置身份或清理数据。
+- SSH 未知：回到本机面板检查；云端只显示缓存，不把管理电脑在线当作其他主机连通。
+
+## 协议与限制
+
+这是项目自定义的 `device-center-driver-v1` 协议，不宣称符合 OAuth Device Grant 或通过生产安全审计。配对体验参考 [RFC 8628 的设备确认和远程钓鱼提醒](https://www.rfc-editor.org/rfc/rfc8628.html#section-5.4)，不能只凭设备名称批准陌生请求。
+
+云端保存公钥和 SHA256 指纹；配对码只保存 SHA256 摘要。所有者在现有个人登录边界内一次性批准，SQLite 事务消费请求，最多 16 个有效 Driver。机器轮询和回报需本机私钥签名，不依赖浏览器 cookie 或长期 Bearer token。签名涵盖固定协议、HTTPS Origin、POST 路径、Driver / 配对 ID、时间、随机数及排序后 JSON 的 SHA256；使用 Node 内置 Ed25519。随机数在 SQLite 保存三分钟，时间窗口 90 秒，拒绝重放，包括进程重启后的重放。
+
+请求与响应上限 16 KiB，固定字段白名单；全实例每分钟最多八个配对申请；候选版本的查找与批准各自每账号八次、全实例各六十四次，最多 32 个待处理请求；配对轮询至少约五秒，回报至少 15 秒。公共申请入口仍可能遭遇拒绝服务，不适合直接扩为公开多用户托管。过期的配对请求与防重放记录按协议时效淘汰；已登记设备和回报不会自动清理。
+
+当前测试验证隔离环境中的协议和 HTTP 接口。实际身份生成、用户批准、目标平台常驻、真实网络下连续回报需要由使用者执行接入后验收；不能以测试数据冒充已绑定设备。远程命令、文件传输与中继任务权限没有因配对而授予。
+
+## 账号归属与候选版本
+
+当前源码 beta.2 增加显式多用户账号隔离，未发布或部署；npm beta.1 客户端的机器配对/签名协议保持兼容。个人模式仍为默认；多用户的面板批准需同时提交码与完整指纹，归属只取服务核验的账号，不接受客户端 tenantId。历史个人记录不自动转移；多账号数据不能交给旧的无隔离服务器读取。详见[托管接入、迁移与回退](hosted-access.md)。

package/docs/hosted-access.md

@@ -0,0 +1,52 @@
+# 本机、官方与自建接入
+
+本版本 0.2.0-beta.1 使用同一 CLI 支持官方与自建 HTTPS 控制面；每个账号独立管理自己的设备。安装不自动接入，connect --confirm 默认申请官方服务，用户登录并核对批准后才绑定。
+
+## 用户流程
+
+1. **本机使用**：运行 Driver → 添加本机智能体的 MCP → 导入已有 SSH。本机没有平台注册要求，只监听回环地址。
+2. **需要云端面板**：本机侧栏点“云端面板” → 官方控制面或自建 HTTPS 域名 → 复制命令，在自己的电脑运行。
+3. **确认归属**：登录对应面板的账号 → 输入终端上的五分钟配对码 → 核对完整公钥指纹和分享范围 → 批准 → 等待首次真实回报。
+
+官方多用户模式复用 App Services 的已验证账号；每账号最多16台有效 Driver、100MiB/UTC日密文中转。执行命令前需 Node.js 24，支持 macOS/Linux。安装不会自动配对，复制不会执行，配对不会安装常驻服务。
+
+同一 CLI 的 `--cloud` 指向所选控制面；默认只回报本机名称、系统、内存、磁盘。SSH 名称与缓存回报需要命令申请并在面板再次批准。私钥不托管到云端、不包含在复制命令、prompt 或下载包中。
+
+## 部署者选择账号模式
+
+保持现有私有配置不变或明确设置 `accountMode: "personal"`，仍只接受配置的 `ownerEmail`；密码方式仍只支持个人模式。不会因为升级源码就允许其他账号进入。
+
+本地验证后的候选可显式配置 App Services 多用户模式，示例均为占位信息：
+
+```json
+{
+  "provider": "app-services",
+  "accountMode": "multi-user",
+  "backendOrigin": "https://appapi.example.com",
+  "accountOrigin": "https://example.com"
+}
+```
+
+该模式只允许上游已验证的非匿名 email/Google/Apple 账号；本项目不新增注册接口。所有参与域名必须属于同一受信任父域名，并复用既有共享 HttpOnly 会话。不是任意第三方域名的 OAuth 登录实现。
+
+服务器从固定上游 `/v1/me` 核验身份，将发行方与稳定 `profile.id` 的摘要作为租户命名空间；不按邮箱合并用户，也不信任客户端的 userId、tenantId、HTTP 头或 JWT 自解码。每次受保护请求只解析一次身份，列表、统计、回报展示、撤销与设备上限均使用该命名空间。机器回报的归属只能来自已登记 Driver，不能由请求指定。
+
+多用户批准要求有效码与完整指纹，事务只允许消费一次。登记请求在批准前没有账号归属；持有配对码的账号可以查找，所以只在你自己的终端和面板之间使用，核对浏览器当前登录账号。批准后其他账号的查找/再次批准不可见，撤销其他账号的设备返回与不存在相同的 404。
+
+### 旧个人数据与回退
+
+`cloud_drivers.tenant_id` 是增量列；历史记录保留为 `cloud-owner`，不会删除、按设备名称合并或自动移交。
+
+已有历史记录的部署切换为多用户时，必须在仓库外的私有配置中增加 `legacyOwnerId`，值为**通过可信 `/v1/me` 核验过的原所有者稳定 profile.id**。它仅把原所有者映射回历史命名空间，其他账号使用各自摘要；没有映射时启动拒绝，避免历史设备被遗失或错误归属。不要填邮箱、浏览器自报 ID 或另一个用户 ID。该值不是私钥，也不应放进公开配置示例或日志。
+
+上线前备份 SQLite 与私有配置并验证映射。回退至个人模式只显示历史所有者设备，其他账号行保留。较旧的不支持租户查询的服务器版本会读出所有账号，因此**有多账号数据之后不可直接回退旧代码**：应停止服务并恢复切换前的完整数据库/配置备份，保留切换后备份供恢复。不能只切换二进制或 current 链接。
+
+## 实际能力与边界
+
+已实现账号隔离、一次性批准、签名资源回报与撤销，以及 TLS 1.3 双向认证的指定日志读取。两端必须独立核对指纹并在目标授权；绑定本身没有操作权限。获准 LAN 精确地址优先，网络不可达时回退 HTTPS 密文中转。见[远程日志](remote-access.md)。
+
+每天每账号100MiB、全实例1GiB持久计数；单会话60秒、每账号2/全实例8并发、每方向16KiB/s。签名 nonce 全实例4096/180秒，公共登记8/分钟/32待批准；查找/批准每账号8/分钟/全局64/分钟。内存限流会随重启重置，日流量不会。当前固定默认额度，尚无计费、付费服务或 SLA。
+
+任意命令、通用文件传输、云端 MCP、Windows 原生 Agent、CF 专用适配器和自动配置迁移尚未提供。自建/官方使用相同中转实现；CF 仅可作为用户自行配置的 HTTPS 前置。
+
+隔离测试使用临时身份与注入上游，验证真实 Node TLS、中转密文、权限、账号和配额。它们不是对真实用户设备的授权验收，也不构成第三方安全审计。

package/docs/npm.md

@@ -0,0 +1,37 @@
+# npm / npx 分发
+
+MIT，Node.js 24，macOS/Linux。当前版本 `0.2.0-beta.1`，使用 npm `beta` 渠道；是否上架以公开 registry 为准。
+
+```sh
+npx --yes device-center@0.2.0-beta.1 --help
+npx --yes device-center@0.2.0-beta.1 plan
+# 主动接入默认官方服务，执行后在终端与面板之间核对配对
+npx --yes device-center@0.2.0-beta.1 connect --confirm
+# 自建服务
+npx --yes device-center@0.2.0-beta.1 connect --cloud https://你的控制面域名 --confirm
+# 仅本机，无账号要求
+npx --yes device-center@0.2.0-beta.1 start
+```
+
+安装与无参/help/version/plan 不生成身份，不配对，不自动启动后台进程。复制命令不含凭据。只有 connect --confirm 才生成本机身份并申请绑定；默认官方地址不会自动批准，用户需登录自己的账号。SSH 缓存分享须 --share-ssh 与面板再次批准。
+
+面板和本机 MCP：`http://127.0.0.1:5174/`、`/mcp`。常驻先固定安装：
+
+```sh
+npm install -g device-center@0.2.0-beta.1
+device-center service plan --port 5174
+# 自行停止同端口前台进程，再主动安装
+device-center service install --port 5174 --confirm
+```
+
+数据在用户应用数据目录，更新包不重置身份或数据库；npx 缓存不得用作常驻目录。Windows 原生身份存储和用户服务尚未提供。
+
+远程指定日志需两端各自明确授权，见[远程日志](remote-access.md)。无通用远程命令或文件传输。
+
+## 发布验证
+
+包采用显式白名单，没有 install/postinstall/prepare 钩子；数据库、身份、SSH、认证配置、部署记录和测试不发布。标准 TLS 使用 Node/OpenSSL，X509 创建使用固定版本 @peculiar/x509 与 reflect-metadata，`npm-shrinkwrap.json` 固定传递依赖和 integrity；不再是零依赖包。源码解压后先 `npm ci --ignore-scripts`。
+
+发布前运行 check/test/verify:package；后者在独立临时 HOME 中无凭据从官方 registry 取得依赖，随后离线安装本次 tar、检查真实 bin/npx/前台 HTTP。候选归档、逐文件摘要、Git 基线、dirty 快照事实及验证结果保留在本机 npm-candidates。只清理本次测试临时目录，不清理用户数据。工作区快照不称为 main CI 构建。
+
+固定新版本 `npm publish <已验证tar> --access public --tag beta`。密码、发布验证与 OTP 由用户在 npm 官方页面自行处理，不进聊天或归档。发布后匿名查询 registry、核对 SHA512 integrity 和 tar 字节，并运行帮助/计划。GitHub 仓库公开与 npm 发布是独立操作，本轮不改变 GitHub 可见性。

package/docs/onboarding.md

@@ -0,0 +1,43 @@
+# 从首次使用到添加设备
+
+> 0.2.0-beta.1 更新：账号隔离、TLS 1.3 双向认证密文中转、独立授权的日志尾读及获准精确 LAN 优先已实现。旧文中的“尚未实现”传输描述属于此前阶段；实际操作与边界以 [远程日志](remote-access.md) 和 README 为准。通用远程命令、文件传输、Windows 原生 Agent 与自动迁移仍未提供。
+目标是让用户只完成必要的复制、粘贴和确认。面板统一用“管理电脑 → 智能体 → 设备”三步引导；部署、协议、常驻服务和排查放到文档或展开说明。下面区分已实现与待实现，不能把目标流程当成已接通。
+
+## 当前本机原型
+
+1. **启动后打开面板。** 原生服务所在电脑自动成为设备，内存与磁盘来自真实本机采集，无需再次添加。点“开始使用”，自动跳到尚缺接入记录的步骤。
+2. **连接智能体。** 复制本机 MCP 地址，在本机 Codex 设置中添加并 Restart；命令行方式可选。已有配置只需检查。只有真实、近期的初始化记录才标记此步骤；记录不是客户端身份或持续在线。也可“稍后连接，先导入设备”，不会虚构接入成功。
+3. **导入已有设备。** 一键导入本机检查通过的 SSH 别名；已导入条目去重，不支持或不完整条目给出原因。保存本地引用后，自动排队检查新增设备的当前 SSH 路径，最多两台并发；在列表和导入步骤标出结果。私钥留在本机，不修改主机配置。失败可在设备卡片重试，无需重新导入。
+
+开始使用、侧栏智能体连接和设备导入在同一个向导中切换。用户可回看管理电脑、跳步或关闭；关闭返回原入口，设备列表滚动位置保留。后续手动新增 SSH 别名仍从“添加设备”进入。不能安装设备 Agent 的机器继续显示未知。
+
+## 服务器 / Docker 部署后的接入
+
+控制面与管理电脑可能是两台机器。当前服务只读取自己所在机器的配置；服务器配置不能代替用户电脑的配置，Docker 也不会取得宿主 SSH 权限。
+
+当前支持 macOS/Linux 管理 Driver，需要 Node.js 24，操作收敛为：
+
+1. 打开云端面板，点 **连接我的电脑**。
+2. 复制固定版本 npx 命令，在自己的电脑终端运行（也可下载源码并在源码目录运行）。回面板输入终端配对码，核对完整公钥指纹并批准；不搬运 SSH 密钥或填写私网地址。需要 Node.js 24，尚无签名安装包。
+3. 管理电脑实际回报后，云端显示名称、内存和磁盘。本机面板继续提供 **智能体 → 设备**：智能体连接本机 Driver 的 MCP，一键导入该电脑的 SSH 引用。云端目前不能执行这些检查或远程任务。
+
+Driver 主动建立获准的安全出站连接。短时一次性登记凭据应由用户单独交互输入，不嵌入 prompt、脚本、压缩包或日志。身份私钥在设备生成并保留，SSH 私钥、身份路径、局域网端点与认证留在管理电脑。云端只同步经用户批准的非秘密登记信息和明确可见范围的回报；导入不转移任务权限、主机信任或在线状态。
+
+个人云端面板的 HTTPS、所有者登录、管理 Driver 配对、签名回报与撤销已经实现；未绑定时显示空列表，不读取服务器 SSH。默认仅回报本机指标，SSH 名称与缓存状态需要双重显式批准。**尚未实现：** 独立资源设备 Agent、Windows Driver、签名安装包、系统钥匙串封装与配置迁移。完整操作与排查见[域名绑定](driver-binding.md)。没有演示绑定成功。管理电脑离线时，依赖它的 SSH 路径不可用；云端面板在线不会替代它完成认证。
+
+本机侧栏也可点“云端面板”，选择官方控制面或自己的 HTTPS 域名后复制命令。当前源码 beta.2 候选支持显式多账号隔离，尚未发布或部署；官方线上仍为个人模式。账号模式和历史数据迁移见[托管接入说明](hosted-access.md)。
+
+## 后续添加新设备的目标流程
+
+| 目标设备条件 | 用户最少操作 | 结果条件 |
+| --- | --- | --- |
+| 管理电脑已有可用 SSH 配置 | 一键导入引用 | 导入后自动检查一次，取得真实资源后才显示近期在线与资源 |
+| 目标设备已有智能体 | 复制安装指导，交给目标机智能体；确认安装与绑定 | 安装包验签、设备本机身份、短期凭据交互与真实回报；待实现 |
+| 目标设备没有智能体 | 下载对应平台的验签安装包，在目标机运行并批准绑定 | 与智能体辅助方式使用同一接入协议；待实现 |
+| 不能安装 Agent，也没有可用 SSH | 明示缺少接入条件 | 保持未知，不伪装接通 |
+
+默认连接偏好是获准局域网入口优先，中转备用；中转可选用户自建、Device Center 服务或 Cloudflare。仅在网络失败时回退，身份/认证异常停止。策略目前只保存为计划，实际认证直连、选路器与新中继适配器仍待实现。不会扫描网段、自动创建隧道或让用户先手动复制长期密钥。
+
+## 日常使用
+
+打开设备列表即可看当前路径和真实快照；导入后执行一次固定只读检查，后续检查由用户发起。后续智能体通过连接器请求范围明确的日志/构建/计算操作，按设备和任务授权；当前没有这些远程任务工具。修改连接偏好不会改变授权。错误应明确发生在 Driver 接入、配置导入、SSH 认证或资源采集哪一步，保留可重试入口，不用重新走完整流程。