@skylandnpm/octopus-proxy 0.1.61 → 0.1.63

package/README.md

@@ -16,7 +16,7 @@ octopus-proxy identity
 
 向导默认使用 `https://octopus.wuyehao.com` 作为 Hub 地址；按需可输入其他地址，或用 `--hub-url` 指定。再次运行向导时会读取现有配置，直接回车即可保留各项设置；机器人 Secret 只提示已配置，不在终端显示原值。macOS 上选择编码工具时，向导优先显示已配置或探测到的命令路径，否则给出该工具的 macOS 路径示例；回车后会检查文件可执行性并运行版本命令，失败时要求重新输入。无交互环境可使用 `octopus-proxy onboard --non-interactive`，未提供 `--hub-url` 时也使用该默认地址；完整选项见 `octopus-proxy help`。安装服务后可运行 `octopus-proxy status` 和 `octopus-proxy doctor` 检查状态。
 
-Proxy 主动连接 Hub 的 `/ws/proxy-chat`，无需开放入站端口或安装 sshd。Claw 经 `/ws/claw-chat` 建立到 Proxy 的内层 TLS 1.3 会话；Hub 只转发加密字节。首次打开工作区显示主机公钥指纹，点击 Trust 后按 Hub 地址和机器人 ID 固定；之后指纹变化会拒绝连接。每次连接都要输入运行 Proxy 服务账号的主机密码，由主机上的 PAM（Linux）或 Open Directory（macOS）验证。断线或连续 60 分钟没有用户操作后需要重新认证。服务安装时生成主机身份，`octopus-proxy identity` 可在主机上查看指纹。安装主机需提供 OpenSSL 和 C 编译器；Linux 还需 PAM 开发头文件。机器人 Secret 仅用于 Hub 路由，不能单独授权工作区。
+Proxy 主动连接 Hub 的 `/ws/proxy-chat`，无需开放入站端口或安装 sshd。Claw 经 `/ws/claw-chat` 建立到 Proxy 的内层 TLS 1.3 会话；Hub 只转发加密字节。首次打开工作区显示主机公钥指纹；核对后点击 Trust，未授权设备还需输入主机终端生成的一次性配对码。Proxy 校验设备签名、配对码及主机密码并持久化设备授权，Claw 在认证成功后按 Hub 地址和机器人 ID 固定指纹；之后指纹变化会拒绝连接。每次连接都要输入运行 Proxy 服务账号的主机密码，由主机上的 PAM（Linux）或 Open Directory（macOS）验证。断线或连续 60 分钟没有用户操作后需要重新认证。服务安装时生成主机身份，`octopus-proxy identity` 显示指纹并开启 5 分钟的设备配对窗口。安装主机需提供 OpenSSL 和 C 编译器；Linux 还需 PAM 开发头文件。机器人 Secret 仅用于 Hub 路由，不能单独授权工作区。
 
 macOS 12.3 及以上运行 `octopus-proxy onboard` 时，配置保存后、服务启动前会准备截屏辅助程序并申请系统屏幕录制权限；已授权时不会重复弹窗。交互模式和 `--non-interactive` 均执行此步骤，`--no-install-service` 也会申请。请在系统弹窗中允许访问；拒绝、超时或辅助程序编译失败时，向导提示原因与授权路径，并继续初始化。在“系统设置 → 隐私与安全性 → 屏幕录制（或屏幕与系统音频录制）”中应授权弹窗显示的实际程序，可能是 Terminal、iTerm、编辑器或 node，不保证出现 `octopus-desktop-capture`。onboard 和 doctor 会显示辅助程序路径，文件名不等于系统授权名称。终端授权不代表后台服务已授权，需在 Claw 点击截屏，让实际服务申请权限，按实际名称授权后重启 Proxy。Linux 没有通用的截屏授权弹窗，需使用桌面用户的图形会话环境；平台依赖与设置见[桌面快照说明](../../docs/claw-desktop-snapshots.md)。
 
@@ -62,6 +62,27 @@ Claw 完成主机信任和账号认证后，通过端到端会话向 Proxy 发
 
 Codex 和 ZCode 由 Proxy 按授权项目启动各自的 app-server，默认随 Proxy 自动启动；服务未就绪时也可在 Claw 点击“启动服务”。若命令不可执行或某个项目启动失败，工作区会显示失败项目及原因。修改命令路径或授权项目后，运行 `octopus-proxy restart` 使配置生效。
 
+## Claw 设备配对与撤销
+
+每台 Claw 与该 Proxy 首次建立授权关系时配对一次。先在运行 Proxy 服务的主机终端执行（自定义配置带上 `--config <path>`）：
+
+```bash
+octopus-proxy identity
+```
+
+命令显示主机完整公钥指纹、6 位数字配对码及到期时间。请核对 Claw 显示的主机指纹，再输入配对码及服务账号密码。配对码 5 分钟内有效，仅能授权一台新设备；每次运行 `identity` 都废止旧码，最多允许 5 次失败配对提交，跨设备和连接累计。`octopus-proxy identity --cancel` 可立即关闭窗口。Proxy 服务未运行时，命令显示指纹并报错，不生成不可使用的配对码。
+
+一个 Proxy 支持多台 Claw 同时在线，最多 32 条并发隧道。添加下一台设备时重新运行 `identity`，已有授权和连接不受影响。已授权设备重连、Claw 重开、Proxy 重启或更新均无需再次配对，但每条新连接仍需主机密码认证。配对码只保存在服务内存中，重启即失效；设备授权单独保存在状态目录的 `authorized-devices.json`（权限 `0600`），按 Hub origin、机器人 ID 和设备公钥隔离。
+
+```bash
+octopus-proxy devices
+octopus-proxy devices --revoke <设备ID>
+```
+
+撤销立即断开该设备的全部会话，其他设备继续工作。设备私钥丢失、授权被撤销或授权数据被清空后须重新配对。Claw 仅重置本地主机信任时须重新核对主机指纹；相同设备公钥仍获授权时不必重复配对。首次升级到支持设备授权的版本后，历史 Claw 也须配对一次；请同时更新 Proxy 和 Claw，旧协议不允许绕过授权。
+
+本机管理接口是状态目录内权限为 `0600` 的 Unix socket，仅服务账号可使用。验证码、密码不写入日志或 Hub 的可读消息。设备授权认证的是获准公钥的私钥持有者，不判断客户端是否来自官方发行包；首次主机指纹核对仍然必要。
+
 ## Pi agent
 
 支持 Pi coding agent 的 RPC 模式，验证基线为 `@earendil-works/pi-coding-agent` **0.87.1**（旧 npm 包名为 `@mariozechner/pi-coding-agent`）。先安装 Pi，在代理运行用户下启动 `pi`，用 `/login` 配置提供商；也可按 Pi 文档配置 API key 环境变量或 `~/.pi/agent/models.json`。系统服务需要能读取相同的凭据和环境。
@@ -125,7 +146,7 @@ octopus-proxy status
 
 这不是旧 macOS 独有的问题：在 macOS 26.6.2 的 `/usr/bin/openssl`（LibreSSL 3.3.6）上也已复现。Proxy 通过 PATH 查找 `openssl`，只用它生成身份文件；实际 TLS 连接使用 Node 自身的 OpenSSL。交互终端和 launchd 服务的 PATH 可能不同，因此终端安装新版 OpenSSL 不代表服务会使用它。升级 macOS 或替换命令不会自动转换已有身份文件。
 
-包含此修复的版本会在启动或运行 `octopus-proxy identity` 时检查身份编码，把旧的显式参数转换为 `named_curve` 并重新签发证书，保留原来的私钥数值和公钥。正常的命名曲线证书不会重写，已有指纹保持不变；TLS 1.3、主机密码认证和指纹校验保持原有要求。转换旧证书后，编码变化会使其 SHA-256 指纹变化；首次连接应与主机上的 `octopus-proxy identity` 输出核对。使用自定义配置时带上原来的 `--config <path>`。
+包含此修复的版本会在启动或运行 `octopus-proxy identity` 时检查身份编码，把旧的显式参数转换为 `named_curve` 并重新签发证书，保留原来的私钥数值和公钥。正常的命名曲线证书不会重写，已有指纹保持不变；TLS 1.3、主机密码认证和指纹校验保持原有要求。转换旧证书后，编码变化会使其 SHA-256 指纹变化；首次连接应与主机上的 `octopus-proxy identity` 输出核对（该命令同时会重新开启配对窗口，废止旧配对码）。使用自定义配置时带上原来的 `--config <path>`。
 
 命名曲线编码遵循 [RFC 5480 §2.1.1](https://www.rfc-editor.org/rfc/rfc5480#section-2.1.1)，继续使用 P-256 和 SHA-256。兼容处理不启用旧 TLS 协议、不放宽客户端证书解析，也不自动覆盖已固定的主机指纹。macOS 26 及后续版本保持这些安全要求；当前实机验证环境为 macOS 26.6.2，后续系统版本仍需实际回归验证。