@landh93/web-codex-client 0.1.0-rc.1

package/NPM_RELEASE.md

@@ -0,0 +1,76 @@
+# npm 客户端发布与安装
+
+包名：`@landh93/web-codex-client`。首版为 `0.1.0-rc.1`，使用 `next` 标签。仅支持 Linux / Node.js 24；这是独立安装候选版，不代表公网、多人或真实模型执行已完成生产验收。`remote-wss-v1` 明确允许远端 WSS，继续使用固定 Noise 加密、TLS 校验及本机指纹授权，不新增任何加密实现。项目尚未选定开源许可证，包暂保留 `UNLICENSED`；第三方代码许可见包内 `sdk/THIRD_PARTY_NOTICES.md`。
+
+## 用户安装
+
+```bash
+npm install -g @landh93/web-codex-client@next
+web-codex-client configure
+web-codex-client doctor
+web-codex-client run
+```
+
+无需安装 pnpm、Rust 或构建工具。Codex 及其私有 Unix socket 必须在这台机器可用；本包不会安装或重启 Codex。交互配置依次输入 WSS Origin、Codex socket（回车使用默认值）、设备 token（隐藏输入）。设备 token 来自 Web 工作台的设备注册，**不是 npm 发布 token**。
+
+配置默认位于 `${XDG_CONFIG_HOME:-$HOME/.config}/web-codex-client/config.json`，可用 `--config FILE` 或 `WEB_CODEX_CLIENT_CONFIG` 指定。状态目录和 token 文件分别为 0700/0600。重新配置保留身份和授权；运行中的 Client 需先停止再配置。升级包不改动用户配置；配置不会写入 npm 安装目录。
+
+非交互环境可以通过标准输入配置，token 不放在参数、URL 或 shell 历史中：
+
+```bash
+web-codex-client configure --relay wss://relay.example.com --token-stdin < /path/to/private-device-token
+```
+
+`doctor` 检查配置及 token 权限、WASM 完整性、WSS 设备认证和 Codex 初始化，不读取历史或调用模型。已有本地 Client 在线时复用其状态，不抢占连接；没有运行时创建一次短暂的设备认证连接，**同一设备 token 不要在其他机器同时使用**。报告默认是配置目录中的 `doctor-report.json`，不含 token、私钥、历史或上游原始报错。支持 `--quiet`、`--report PRIVATE_PATH`。失败阶段落盘后退出非零。
+
+使用公开 CA 证书时通常无需额外设置；私有 CA 可在启动 Node 前设置 `NODE_EXTRA_CA_CERTS=/path/to/ca.pem`。禁止 `NODE_TLS_REJECT_UNAUTHORIZED=0`。Nginx 要正确代理 `/ws/v1/client`，token 经 Authorization 头发送。
+
+Client 运行后，在另一终端执行 `web-codex-client pair-open`、`pair-list`，核对浏览器的完整指纹，再用 `pair-approve --fingerprint FULL_HASH --root /absolute/project` 授权。默认只读，需要执行任务时才加 `--write`。这些命令自动使用配置中的 stateDir；旧的 `--state` 用法仍有效。
+
+后台常驻可使用 systemd 用户服务，将 `ExecStart` 设为实际安装的 `web-codex-client run --config /absolute/config.json`。npm 安装不会自动启用服务或打开配对窗口。
+
+## 发布前验证
+
+```bash
+cd client
+pnpm install --frozen-lockfile
+pnpm build
+pnpm typecheck
+pnpm test
+pnpm test:package
+```
+
+包安装测试在仓库外的临时目录安装真实 tgz，使用合成 Codex、TLS 中继和 Noise 浏览器端点检查配置、认证、配对、请求、重连与模拟升级。不会使用现有本机凭据或重启用户 Client。输出真实阶段进度，支持 `--quiet`；报告在被 Git 忽略的 `.test-output/`。发布包使用明确的文件白名单，不含源码映射、测试凭据、npmrc、运行状态或项目历史。
+
+## 配置 npm 发布 token
+
+在 npm 网站的账号菜单 → Access Tokens → Generate New Token 中创建 granular token。为 `@landh93` scope 授予包发布的读写权限；首次发布时需要 scope 权限，不能只选择尚不存在的包。设置较短有效期。若希望该 token 在无人值守发布时不再要求 OTP，可选择 Bypass 2FA；否则在发布时完成交互式二次验证。包自身的发布策略仍可能拒绝 token 发布。
+
+在**本机终端**执行以下 Bash 命令。token 输入不回显，文件不进仓库；不要把 token 发到聊天里：
+
+```bash
+set +x
+mkdir -p "$HOME/.config/web-codex-npm"
+chmod 700 "$HOME/.config/web-codex-npm"
+read -r -s -p 'npm granular token: ' WC_NPM_PUBLISH_TOKEN
+printf '\n'
+(umask 077; printf '//registry.npmjs.org/:_authToken=%s\n' "$WC_NPM_PUBLISH_TOKEN" > "$HOME/.config/web-codex-npm/npmrc")
+unset WC_NPM_PUBLISH_TOKEN
+chmod 600 "$HOME/.config/web-codex-npm/npmrc"
+npm whoami --registry=https://registry.npmjs.org/ --userconfig="$HOME/.config/web-codex-npm/npmrc"
+```
+
+确认输出账号是 `landh93` 或具有该 scope 发布权限的账号后，告知“已配置”。无需提供 token 内容。单独终端的环境变量不会自动传入 Codex 会话，因此这里使用独立私有 npmrc，而不是仅 export 一个临时变量。
+
+随后发布已通过验证的**具体 tgz**，不重新构建另一个包：
+
+```bash
+npm publish .test-output/landh93-web-codex-client-0.1.0-rc.1.tgz \
+  --access public --tag next --ignore-scripts \
+  --registry=https://registry.npmjs.org/ \
+  --userconfig="$HOME/.config/web-codex-npm/npmrc"
+```
+
+发布完成后核对 registry 的版本和 integrity，再从 registry 全新安装并检查 `--version`。同版本不能覆盖；更新时递增版本、重新验收，再发布。发布流程不上传设备 token、CA 私钥、Client 身份或认证数据库。
+
+官方参考：[创建 token](https://docs.npmjs.com/creating-and-viewing-access-tokens/)、[npmrc 凭据配置](https://docs.npmjs.com/cli/v11/configuring-npm/npmrc/)。

package/README.md

@@ -0,0 +1,123 @@
+# Web Codex Client
+
+本机连接程序 + 共享加密 SDK。只维护本目录；Server/React UI 由独立任务负责。当前本机只读部署已验收，使用方式见 [本机运行说明](../LOCAL_RUNBOOK.md)，结论与边界见 [联合报告](../INTEGRATION_REPORT.md)。
+
+已实现 Noise XX 双向加密、WSS 主动连接/心跳/退避重连、本机配对授权、Codex 双向 JSON-RPC、项目与历史查询、受限文件资源、执行白名单、写租约、审批/提问、内存补发/去重。无对话数据库、无明文中继模式，不读取 OpenAI 登录文件。
+
+环境：Linux、Node.js 24；源码开发使用 pnpm 11.17.0，测试还需要 OpenSSL 和 Chromium。文件句柄安全校验使用 Linux `/proc/self/fd`，尚未提供其他 OS 实现。
+
+## npm 安装与连接
+
+包名为 `@landh93/web-codex-client`，候选版本使用 `next` 标签。发布后可直接安装：
+
+```bash
+npm install -g @landh93/web-codex-client@next
+web-codex-client configure
+web-codex-client doctor
+web-codex-client run
+```
+
+`configure` 交互输入 WSS 地址、Codex socket 和隐藏的设备 token，保存在用户配置目录。`doctor` 检查私有配置、WASM、WSS 认证和 Codex 初始化，失败退出非零；既有 Client 在线时不会抢占它的连接。支持 `--quiet`。安装和升级不会重启 Codex，也不会自动批准浏览器。
+
+另开终端运行 `web-codex-client pair-open`，浏览器连接后用 `pair-list` 核对完整指纹，再 `pair-approve --fingerprint FULL_HASH --root /absolute/project`。配置、身份和授权独立于 npm 安装目录，升级时保留。完整安装、token 标准输入、证书、后台运行与发布说明见 [NPM_RELEASE.md](./NPM_RELEASE.md)。
+
+## 安装、构建、自测
+
+在 `client/` 下运行：
+
+```bash
+pnpm install --frozen-lockfile
+pnpm build
+pnpm typecheck
+pnpm test
+```
+
+`pnpm test` 自动生成仅供 loopback 测试的短期证书，然后运行单元/协议/合成 WSS 测试。测试环境必须允许子进程管道、Unix Socket 和 loopback TCP。证书与私钥在 `/tmp/web-codex-tls/`，不得用于部署。
+
+```bash
+pnpm exec playwright install chromium
+pnpm test:browser
+NODE_EXTRA_CA_CERTS=/tmp/web-codex-tls/cert.pem pnpm test:cli
+```
+
+Chromium 已装在其他位置时可设置 `CHROMIUM_EXECUTABLE=/absolute/path/to/chrome`。本次实测使用 `/tmp/web-codex-browsers/chromium-1187/chrome-linux/chrome`。浏览器测试基于真实完成的四个阶段显示百分比、耗时、速率和 ETA；只使用合成数据。
+
+已发布 SDK：`artifacts/web-codex-bridge-sdk-0.1.0-rc.3.tgz`。Server 复制该文件到自己的 `vendor/` 后安装并固定锁文件，核对同名 `.sha256`。不要覆盖已发布文件，也不要通过 link: 指向本目录源码。构建后 `pnpm pack:sdk` 会拒绝覆盖已有版本；修改 SDK 需先调整 `scripts/build.mjs` 中的版本。
+
+## 启动与本机授权
+
+先取得 Server 提供的设备中继凭据和 WSS 地址。配置实例见 `deploy/config.example.json`。本机使用 `cryptoPolicy:"local-reviewed-v1"`，只允许回环 WSS；远端使用 `cryptoPolicy:"remote-wss-v1"`，示例见 `deploy/config.remote.example.json`。远端策略只明确放行 WSS 主机，不代表新增生产安全审查；TLS、固定 Noise 套件、完整指纹与本机授权照常执行。`experimentalCrypto:true` 保留兼容已有开发联调配置。工程审查与第三方审计边界见 [CRYPTO_REVIEW.md](./CRYPTO_REVIEW.md)。
+
+```bash
+mkdir -p ~/.config/web-codex-client
+chmod 700 ~/.config/web-codex-client
+cp deploy/config.example.json ~/.config/web-codex-client/config.json
+# 修改 relayUrl、upstream.socket；把 Server 给出的 token 写入 device-token 文件。
+chmod 600 ~/.config/web-codex-client/device-token
+node dist/cli.js init --state ~/.config/web-codex-client/state
+node dist/cli.js run --config ~/.config/web-codex-client/config.json
+```
+
+中继仅允许 WSS；不会禁用 TLS 验证。自签名开发证书使用 `NODE_EXTRA_CA_CERTS`。长期 token 不放 URL 或命令参数。设备身份私钥存于 0700 state 目录中的 0600 identity.json；这是磁盘明文身份文件，需要 OS/磁盘保护。授权表只含公钥、规范化工作区路径和读写权限，不含对话。
+
+另开本机终端进行配对：
+
+```bash
+node dist/cli.js status --state ~/.config/web-codex-client/state
+node dist/cli.js pair-open --state ~/.config/web-codex-client/state
+node dist/cli.js pair-list --state ~/.config/web-codex-client/state
+# 浏览器完成握手后，与本地 pair-list 核对完整的 64 位指纹。
+# 在可信浏览器点击确认，再在本机明确授予目录权限：
+node dist/cli.js pair-approve --state ~/.config/web-codex-client/state \
+  --fingerprint FULL_64_CHARACTER_FINGERPRINT --root /absolute/project
+# 需要通过 Codex 执行任务时，审批命令额外加 --write。
+node dist/cli.js revoke --state ~/.config/web-codex-client/state \
+  --peer BROWSER_PUBLIC_KEY_FROM_PAIR_LIST
+```
+
+配对窗口 120 秒，本机确认还要求浏览器已确认相同指纹。默认只读；`--write` 才允许执行和租约。撤销立即关闭该身份的会话并拒绝后续业务。浏览器身份默认仅存内存，刷新后重新配对；同一页面断线重连可以继续使用内存身份和固定公钥。
+
+`status` 分别返回 relayOnline、handshakes、authorizedSessions、codexAvailable。Codex 连接按第一次已授权请求惰性建立，因此仅中继上线时 codexAvailable 仍为 false。上游断线后下一次请求重连，旧 epoch/订阅失效。后台服务无有限总工作量，不显示伪造百分比。
+
+`deploy/web-codex-client.service` 是 systemd --user 模板；调整 Node/项目绝对路径后自行安装启用。本次未修改或启用用户 systemd 服务。每个 stateDir 只运行一个实例；启动时拒绝已有活动控制 socket，并清理同用户拥有的失效 socket。
+
+## Codex 接入与只读诊断
+
+支持 proxy、Unix WebSocket、回环 WebSocket、独占 stdio。默认 Unix WebSocket 直接连接既有私有 socket；proxy 为兼容选项，仅终止自己启动的代理，不终止既有 daemon。stdio 模式必须显式配置独立 codexHome，由 Client 管理该子进程。
+
+```bash
+node dist/cli.js probe \
+  --socket /home/YOUR_USER/.codex/app-server-control/app-server-control.sock \
+  --report /tmp/web-codex-probe.json
+# 安静模式适合 CI；报告只保存方法状态/数量，不保存正文/ID/路径：
+node dist/cli.js probe --quiet --report /tmp/web-codex-probe.json
+# 隔离的真实 CLI 验证（不发送模型请求）：
+mkdir -p /tmp/web-codex-isolated-home
+node dist/cli.js probe --standalone --codex-home /tmp/web-codex-isolated-home \
+  --report /tmp/web-codex-isolated-probe.json
+```
+
+探测六个检查单元，每个结果落盘后更新真实进度；跳过无历史的检查会明确标记 NOT_RUN，不算接口验证通过。初始化或任一实际检查失败都会留下 FAIL 报告并退出非零；没有可用历史时标记 NOT_RUN，不伪装成已验证。非交互进度每秒刷新一次，CI 可使用 `--quiet`。`--binary PATH` 可指定与 daemon 匹配的 Codex 二进制；不要重启活动 daemon 来迁就测试。
+
+现有 daemon 0.153.4 已通过标准 Unix WebSocket 验证初始化、真实项目/对话和有界历史读取；未重启 daemon 或修改已有对话。旧 proxy 超时没有被断言为版本差异。活动任务接管与真实模型写入不在只读验收结论内。
+
+## 数据与预算
+
+- 上游单条 JSON-RPC 8 MiB、并发 32；超限关闭上游并要求重同步。
+- 外层帧 128 KiB；单片明文 32 KiB；完整业务对象 1 MiB；分片 15 秒超时。
+- 历史回退总预算 8 MiB、游标 60 秒；未验证存储不直接解析或迁移。
+- 单设备最多 32 routes；每 route 出站约 1 MiB、入站待处理 64 帧；共享 socket 缓冲上限 4 MiB；超限关闭 route，无静默密文丢包。
+- 最多 128 订阅，每订阅最多 1 MiB/60 秒重放；业务 ACK 释放已确认事件。上游断开或 epoch 不匹配明确 resyncRequired。
+- 写操作 requestId 按身份与参数摘要去重，最多 2048 条/8 MiB；预算耗尽拒绝新写入。所有写操作必须带 epoch，不自动重发；请求结果不明时需要查询上游确认。
+- 文件最大 64 MiB、块最大 32 KiB、最多 64 句柄、60 秒过期。realpath/符号链接/已打开 fd 边界检查，读取前后检测变更。当前文件与历史 diff 分开。
+- 会话最多 1 小时或单方向 1 GiB，到期拒绝继续发送；UI 必须新建 route 和完成新握手，不能重置 nonce。
+
+Unknown Codex item 字段被保留，SDK 提供稳定最小类型。没有可靠快照偏移的 delta 转成 item.invalidated，由 UI 重新读取完整节点，避免重复文字。更多 DTO、事件与调用例子见 `sdk/README.md` 和 `CONTRACT_PROPOSALS.md`。
+
+未实现的主要优化：长历史流式偏移索引、自动会话轮换编排、精细控制/文件队列优先级、文本 delta 合并与 10 分钟性能基准。权限扩展审批只支持拒绝；未开放上传、任意原始 RPC、持久化浏览器私钥或模型配置覆盖。
+
+## 重建锁定加密后端
+
+常规 `pnpm build` 使用仓库内经过摘要校验的 WASM，不需要本机安装 Rust。若修改 Rust binding，需 Rust 1.90.0、`wasm32-unknown-unknown` target 与 wasm-bindgen CLI 0.2.100，然后运行 `pnpm build:crypto`。可用 `WASM_BINDGEN` 指定该 CLI 路径，用 `WEB_CODEX_CARGO_CACHE` 指定独立 Cargo 缓存；脚本默认使用 `/tmp/web-codex-wasm-tools/bin/wasm-bindgen` 和 `/tmp/web-codex-cargo`。脚本先跑独立精确向量，再构建并生成输入/输出摘要清单，三阶段均按实际完成情况落盘并显示进度。运行时只使用固定套件，测试用确定性密钥不在导出的 API 中。
+
+`pnpm test:crypto-soak` 使用已构建 Node WASM 完成 100 个会话、10,000 次双向加密往返；不访问网络、Codex 历史或模型。此测试和浏览器渲染基准需分别解读，不能合并为网络端到端压测。

package/deploy/config.example.json

@@ -0,0 +1,9 @@
+{
+  "relayUrl": "wss://localhost:9443",
+  "deviceTokenFile": "./device-token",
+  "stateDir": "./client-state",
+  "cryptoPolicy": "local-reviewed-v1",
+  "upstream": {
+    "mode": "unix"
+  }
+}

package/deploy/config.remote.example.json

@@ -0,0 +1,7 @@
+{
+  "relayUrl": "wss://relay.example.com",
+  "deviceTokenFile": "./device-token",
+  "stateDir": "./state",
+  "cryptoPolicy": "remote-wss-v1",
+  "upstream": { "mode": "unix" }
+}

package/deploy/web-codex-client.service

@@ -0,0 +1,19 @@
+[Unit]
+Description=Web Codex local encrypted bridge
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+WorkingDirectory=%h/Projects/web-codex/client
+# Replace this path if Node is installed elsewhere. Node >=24 is required.
+ExecStart=%h/.nvm/versions/node/v24.16.0/bin/node %h/Projects/web-codex/client/dist/cli.js run --config %h/.config/web-codex-client/config.json
+Environment=PATH=%h/.nvm/versions/node/v24.16.0/bin:/usr/bin:/bin
+Restart=on-failure
+RestartSec=5
+TimeoutStopSec=15
+UMask=0077
+NoNewPrivileges=true
+
+[Install]
+WantedBy=default.target