@itpay/cli 2.0.14 → 2.0.15

package/docs/skill-bundle-rollout/01-mcp-authentication.md

@@ -0,0 +1,256 @@
+# 核心任务一：MCP 专用认证系统
+
+状态：待实施
+
+## 1. Current State
+
+### CLI Device Authority
+
+当前 `src/state/device_authority.ts`：
+
+- 每个本地安装生成一把 Ed25519 私钥。
+- 私钥和 Device 状态存放在 `~/.itpay-v3/device`，owner-only 权限。
+- 一个 production Device registration 下按 `agent_type` 建立 Agent Instance。
+- CLI 通过 challenge 签名取得短期 Device session。
+- 受保护请求使用 `Authorization: ItPayDevice ...` 加请求签名。
+- session 失效只续期一次；已撤销的 v2 registration 不会静默替换。
+
+这套系统回答的是“哪个本地 Agent 设备在调用”，不是“哪个付费用户连接了 MCP”。
+
+### Buyer Bearer
+
+`src/state/config.ts` 可以从 `ITPAY_BEARER_TOKEN` 读取账号 Bearer token，供 `orders` 等账号范围命令使用。它是外部注入能力，不是平台 OAuth 连接系统，不应直接扩展成把 token 写进 Skill bundle。
+
+### 问题
+
+云端 Chat 平台不能稳定访问用户电脑上的 `~/.itpay-v3`。即使 Skill 在沙箱里写出同名目录，那也是平台执行容器的临时身份，不是用户本机身份，也不能作为订阅、订单或支付权限的长期主键。
+
+## 2. Target Behavior
+
+新增远程 MCP OAuth 通道：
+
+```text
+Platform -> OAuth authorize -> ItPay login/consent
+         <- authorization code
+Platform -> token endpoint (code + PKCE)
+         <- access token + refresh token
+Platform -> MCP tool + Bearer access token
+MCP      -> validate issuer/audience/scope/expiry
+MCP      -> principal.user_id
+Backend  -> account/entitlement/order authorization
+```
+
+完成后：
+
+- MCP 通过 ItPay 用户身份追踪收费、套餐、订单与权限。
+- CLI 继续通过 Device Authority 追踪本地 Agent 设备和 Agent Instance。
+- 用户可以显式把 Device 关联到同一 ItPay account，但关联不改变认证方式。
+- 两套 token 具有不同 issuer/audience、Header scheme、存储位置和撤销域。
+- 后端授权逻辑接收统一 principal，但不混淆 principal 类型。
+
+不应该改变：
+
+- 现有 CLI 私钥位置、Device 注册协议、签名格式和一次性 session 恢复规则。
+- 默认 `https://app.itpay.ai`，且仅允许准确 `https://dev.itpay.ai` 测试 override 的官方 Backend 规则。
+- Checkout 外部人类确认和服务端支付状态权威性。
+
+## 3. Scope
+
+### In scope
+
+- ItPay OAuth Authorization Server 所需的 authorize、token、refresh、revoke 和 metadata。
+- MCP resource server 的 Bearer token 验证。
+- PKCE、state、精确 redirect URI、scope、audience、过期和撤销。
+- OAuth subject 到现有 ItPay `user_id` 的映射。
+- 平台 OAuth client/connection 记录。
+- MCP 工具级 scope 与敏感写操作确认策略。
+- CLI Device 与用户账号的可选显式关联。
+- 审计日志、最小化返回、测试账号和平台审核所需演示凭据。
+
+### Out of scope
+
+- 重写 CLI Device Authority。
+- 让 MCP 读取或迁移本地 Device 私钥。
+- 让平台 Access Token 代替支付确认。
+- 在聊天内容中采集支付卡、支付密码、验证码、钱包私钥。
+- 为每个平台建立独立 ItPay 用户表。
+
+## 4. 认证边界
+
+### Principal 类型
+
+后端至少明确区分：
+
+```ts
+type Principal =
+  | { kind: "device"; deviceId: string; agentInstanceId: string; agentType: string }
+  | { kind: "user"; userId: string; oauthClientId: string; scopes: string[] };
+```
+
+不要求实际代码使用这个 TypeScript 类型，但授权层必须保留等价区分。禁止根据“有 Authorization Header”就把两者当成同一种账号。
+
+### Header 与 audience
+
+| 通道 | Header | audience | 用途 |
+| --- | --- | --- | --- |
+| CLI | `Authorization: ItPayDevice <session>` + 签名 Headers | Device API | 本地设备、Agent Instance、设备额度与执行 |
+| MCP | `Authorization: Bearer <oauth_access_token>` | ItPay MCP resource | 用户账号、套餐、订单和 MCP 工具 |
+
+Bearer token 不能被 CLI Device middleware 接受；Device session 不能被 MCP middleware 接受。鉴权失败返回 401，授权不足返回 403，不做静默降级。
+
+### 服务端身份关系
+
+建议关系而非第二套用户系统：
+
+```text
+itpay_users
+  id
+
+oauth_clients
+  client_id
+  platform
+  redirect_uris
+  status
+
+oauth_grants
+  user_id -> itpay_users.id
+  client_id -> oauth_clients.client_id
+  scopes
+  revoked_at
+
+agent_devices
+  optional_linked_user_id -> itpay_users.id
+```
+
+Access token 的 `sub` 是稳定、不可猜测的 ItPay 用户 subject。若需要减少跨客户端关联，应使用 pairwise subject，并在服务端映射回同一 `user_id`；不要把 email、ChatGPT 用户名或平台会话 ID 当主键。
+
+## 5. Implementation Steps
+
+### Step 1：冻结现有 CLI 认证合同
+
+依赖：无。
+
+- 为现有 Device enrollment、session、请求签名、401 单次恢复补齐合同测试。
+- 记录 Device API 可访问的路由集合。
+- 确认 MCP 改动不会修改 `src/state/device_authority.ts` 的持久化 schema。
+
+完成条件：加入 MCP 中间件前后，现有 CLI 测试结果和本地身份文件保持一致。
+
+### Step 2：定义 OAuth issuer 和 MCP resource
+
+依赖：Step 1。
+
+- 选择正式 issuer，例如 `https://auth.itpay.ai`；若沿用 `app.itpay.ai`，也必须保持独立 OAuth 路径和密钥用途。
+- 发布标准 Authorization Server metadata 和 MCP Protected Resource metadata。
+- 明确 production MCP URL、resource audience、redirect URI 注册规则和允许的平台 client。
+- Authorization Code 必须使用 PKCE；禁止 implicit flow 和 Resource Owner Password flow。
+
+完成条件：平台可以发现授权端点，redirect URI 不能通配，code 只能使用一次且短期有效。
+
+### Step 3：实现登录、同意和 token 生命周期
+
+依赖：Step 2。
+
+- 用户在 ItPay 页面完成登录；平台不能代收 ItPay 密码。
+- consent 页面展示 client、scope、数据用途和撤销入口。
+- access token 短期有效；refresh token 轮换并检测重放。
+- 支持单 grant 撤销、全设备/全连接撤销和用户主动断开平台。
+- 密钥轮换保留合理验证窗口；日志不记录原始 token 或 authorization code。
+
+完成条件：登录、刷新、过期、撤销、重放和错误 redirect URI 均有自动测试。
+
+### Step 4：在 MCP 服务建立认证和工具授权
+
+依赖：Step 3。
+
+- MCP 入口只接受匹配 issuer、audience、签名、有效期和未撤销 grant 的 Bearer token。
+- 每个工具声明并验证最小 scope。
+- 只读工具与创建 Checkout、退款等写工具分开。
+- 敏感写工具保留平台确认和 ItPay 服务端幂等键。
+- 工具响应去掉 token、内部用户 ID、Device ID、调试 payload 和不必要个人数据。
+
+建议第一版 scope：
+
+| Scope | 能力 |
+| --- | --- |
+| `catalog:read` | 浏览公开目录 |
+| `checkout:write` | 创建或恢复当前用户的 Checkout handoff |
+| `orders:read` | 读取当前用户订单摘要 |
+| `refunds:write` | 按既有退款政策发起退款请求 |
+
+不要第一版就增加通配 scope。
+
+完成条件：越权工具返回 403；不能通过参数替换其他用户 ID；写操作保持幂等。
+
+### Step 5：关联账号而不合并凭据
+
+依赖：Step 3、Step 4。
+
+- MCP OAuth grant 直接绑定 ItPay `user_id`。
+- 本地 Device 若需要账号能力，通过网页显式关联到同一 `user_id`。
+- 关联只写服务端关系，不把 OAuth refresh token 写入 `~/.itpay-v3/device`，也不把 Device 私钥传到服务端或 MCP。
+- 解除关联不删除 Device 身份；撤销 OAuth 不删除 Device registration。
+
+完成条件：分别撤销任一通道不会破坏另一通道；同一用户的订单权限由服务端政策决定。
+
+### Step 6：平台审核材料与运维
+
+依赖：Step 4。
+
+- 建立无 MFA、无短信/邮件确认、无内网依赖的审核测试账号，仅含固定测试数据和限额。
+- 准备 privacy policy、terms、support、数据删除和撤销说明。
+- 记录 client、user、tool、scope、结果和 request ID；不记录 secret。
+- 对 token 签发、失败登录、撤销、敏感工具建立告警。
+
+完成条件：审核者可以独立完成正向和负向测试；运营可以按 user/client 撤销连接。
+
+## 6. API / Data / Type Changes
+
+预计涉及，具体路由名在服务端仓库调研后确定：
+
+- OAuth metadata、authorize、token、revoke 端点。
+- MCP protected resource metadata。
+- OAuth client、grant、refresh-token family、consent/audit 数据。
+- 统一但保留 `device`/`user` 区分的 principal 类型。
+- MCP tool scope 和平台 action annotation。
+
+CLI 公共命令和 `~/.itpay-v3/device` schema：无计划变更。
+
+## 7. Tests / Verification
+
+### 单元测试
+
+- PKCE verifier、redirect URI、state、code 单次消费。
+- issuer/audience/scope/expiry/signature/revocation。
+- refresh rotation 和旧 token 重放。
+- Device/Bearer scheme 互相拒绝。
+
+### 集成测试
+
+- 完整 OAuth 登录、MCP 调用、刷新、撤销。
+- 同一 ItPay 用户从两个平台 client 登录。
+- MCP OAuth 登录后，本地 CLI Device ID 和私钥 hash 不变。
+- Device 撤销后 MCP grant 仍按自身状态工作；反向亦然。
+- 订单、Checkout、退款的跨用户越权测试。
+
+### 手动验证
+
+- ChatGPT Connect/Disconnect。
+- 另一个支持远程 MCP OAuth 的平台连接。
+- 本地 CLI 同时运行并完成 `readyz`、目录、Checkout 恢复。
+
+## 8. Risks / Uncertainties
+
+- MCP 服务端代码不在当前 CLI 仓库，本文件定义合同，实施前必须在对应服务端仓库重新追踪现有用户/session 模块。
+- 各平台对动态 client registration、redirect URI 和 token metadata 的细节可能不同；以平台实际连接测试为准。
+- OpenAI 对金融交易和 PCI 数据有额外限制。MCP 只编排外部 Checkout，不把 OAuth 登录等同于付款授权。
+- `ITPAY_BEARER_TOKEN` 的长期定位需要服务端确认；第一版不删除、不重命名，也不让 MCP 依赖该环境变量。
+
+## 9. Checkpoint
+
+本任务不需要改动当前 CLI 身份即可开始。实施时只有以下情况停下确认：
+
+- 现有服务端没有可复用的 ItPay 用户主表；
+- 必须改变 Device principal 或 quota 归属；
+- 需要引入新的支付授权行为；
+- 平台要求与这里冲突的 token 传递方式。

package/docs/skill-bundle-rollout/02-platform-bundle-repositories.md

@@ -0,0 +1,282 @@
+# 核心任务二：多平台 Bundle Skill 仓库与自动同步
+
+状态：待实施
+
+## 1. Current State
+
+当前 CLI 主仓库：
+
+- npm 包名为 `@itpay/cli`，当前版本由 `package.json` 管理。
+- `npm run check` 执行类型检查、测试覆盖率和打包 smoke test。
+- main 分支 CD 在验证后发布精确 npm 版本。
+- npm 包已经包含 `bin/`、`dist/src/`、`docs/`、`skills/`、README 和 LICENSE。
+- CLI 运行依赖 Node.js 18+，并依赖 `commander`、`qrcode`。
+- `skills/itpay/SKILL.md` 是当前通用 Skill 合同，但没有四个平台各自的 manifest、目录结构和商店发布材料。
+
+只复制 npm 包 tarball 并不等于自包含 bundle，因为 npm tarball 不包含生产 `node_modules`。真正的 bundle 必须在发布时装入精确生产依赖，或者未来另行构建单文件/原生可执行文件。
+
+## 2. Target Behavior
+
+建立四个独立平台仓库。每个仓库只维护：
+
+```text
+平台 manifest 和适配说明
+平台专用 SKILL.md
+由自动化生成的 vendor/itpay-cli bundle
+bundle.lock.json
+平台测试与发布材料
+```
+
+CLI 发布后：
+
+```text
+@itpay/cli@X.Y.Z 发布成功
+  -> 通知四个平台仓库
+  -> 下载精确 X.Y.Z 和 npm integrity
+  -> 安装精确 production dependencies
+  -> 生成 bundle 和 lock
+  -> 运行无全局 CLI smoke test
+  -> 创建同步 PR
+  -> 人工审查平台差异
+  -> 合并、打 tag、按平台上传/发布
+```
+
+## 3. Scope
+
+### In scope
+
+- 四个独立仓库和平台 manifest。
+- 通用 CLI bundle 生成脚本。
+- npm 版本、integrity、源 commit 的锁定记录。
+- CLI 发布后的跨仓同步 PR。
+- 无全局 CLI、无运行时 npm 下载的测试。
+- macOS、Linux、Windows 平台适配验证。
+- 平台审核包、release notes 和回滚规则。
+
+### Out of scope
+
+- 把 CLI 源码复制到四个仓库继续开发。
+- 每个平台 fork 一套业务逻辑。
+- 运行时自动执行 `npm install -g @itpay/cli@latest`。
+- 在 CLI 发布时绕过平台审核自动公开商店版本。
+- 第一阶段引入新的单文件打包器或原生二进制工具链。
+
+## 4. 仓库布局
+
+### OpenAI
+
+```text
+itpay-skill-openai/
+  plugin metadata / submission assets
+  skills/itpay/SKILL.md
+  skills/itpay/scripts/itpay
+  skills/itpay/vendor/itpay-cli/
+  bundle.lock.json
+  tests/
+  submission/
+```
+
+ChatGPT 云端工作流优先调用远程 MCP；本地 Codex 在平台允许 shell 且 bundle 可执行时才能使用 bundled CLI。Skill 必须明确这个选择，不能在 ChatGPT 沙箱里把 `~/.itpay-v3` 当长期用户认证。
+
+### Claude Code
+
+```text
+itpay-skill-claude-code/
+  .claude-plugin/marketplace.json
+  plugins/itpay/
+    .claude-plugin/plugin.json
+    skills/itpay/SKILL.md
+    bin/itpay
+    vendor/itpay-cli/
+    .mcp.json               # 远程 MCP 上线时加入
+  bundle.lock.json
+  README.md
+```
+
+一个 Claude 平台仓库同时承载 marketplace catalog 和 ItPay plugin，不另建第五个仓库。Claude Code 会把 plugin root 的 `bin/` 加入 Bash PATH。`bin/itpay` 只负责定位本仓库内 vendor 入口，不搜索或调用全局 `itpay`。
+
+### Gemini CLI
+
+```text
+itpay-skill-gemini-cli/
+  gemini-extension.json
+  skills/itpay/SKILL.md
+  bin/itpay
+  vendor/itpay-cli/
+  bundle.lock.json
+  README.md
+```
+
+manifest 位于绝对根目录。Skill 命令使用 `${extensionPath}` 定位 bundle，不依赖安装目录名称。
+
+### WorkBuddy
+
+```text
+itpay-skill-workbuddy/
+  SKILL.md
+  scripts/itpay
+  vendor/itpay-cli/
+  bundle.lock.json
+  README.md
+```
+
+最终压缩结构以 WorkBuddy 实际上传校验结果为准。当前官方文档确认可以上传本地技能包，但未公开社区 SkillHub 提交 schema，因此不要预先创造私有 manifest。
+
+## 5. Bundle 合同
+
+### 第一阶段产物
+
+第一阶段使用“vendored Node bundle”，不增加打包器：
+
+```text
+vendor/itpay-cli/package/       npm 包内容
+vendor/itpay-cli/node_modules/  仅 production dependencies
+bin/itpay                       平台薄启动器
+bundle.lock.json                来源证明
+```
+
+运行时不得联网安装。宿主必须已有 Node.js 18+。如果某平台审核环境没有 Node，再单独启动“standalone executable”任务；不要在还没有失败证据时提前维护多架构二进制。
+
+### `bundle.lock.json`
+
+至少包含：
+
+```json
+{
+  "schemaVersion": 1,
+  "package": "@itpay/cli",
+  "version": "2.0.14",
+  "npmIntegrity": "sha512-...",
+  "sourceGitSha": "...",
+  "generatedAt": "2026-07-21T00:00:00Z",
+  "node": ">=18"
+}
+```
+
+不要把 token、registry credential、构建机路径或本地身份写入 lock。
+
+### 启动器规则
+
+- 只调用 bundle 内的 CLI 入口。
+- 正确转发全部参数、stdout、stderr 和 exit code。
+- 不修改 `HOME`，使本地平台继续复用真实 `~/.itpay-v3`。
+- 不回退到 PATH 中的另一个 `itpay`，避免同机双版本不确定性。
+- `itpay --version` 必须等于 `bundle.lock.json.version`。
+
+用户全局安装的 CLI 可以同时存在：终端里执行全局 `itpay` 使用全局版本；Skill 内必须调用平台 bundle 的绝对路径或 plugin PATH 中的启动器。两者共享同一 `~/.itpay-v3` Device schema，因此共享本地 Device 身份，但代码版本由调用路径明确决定。
+
+## 6. Implementation Steps
+
+### Step 1：建立 bundle 生成器
+
+位置：优先放在 CLI 主仓库 `scripts/`，四个仓库调用同一已发布脚本或复制极小且固定的生成逻辑。
+
+- 输入必须是精确 semver，拒绝 `latest`、范围和未发布版本。
+- 从 npm registry 读取版本、dist.integrity 和 gitHead。
+- 下载 tarball并验证 integrity。
+- 安装 `--omit=dev --ignore-scripts` 的精确生产依赖。
+- 删除 npm cache、测试临时文件和不需要的元数据。
+- 生成 `bundle.lock.json`。
+
+依赖：现有 npm 发布成功。
+
+### Step 2：建立四个平台仓库
+
+- 每个仓库只保留一个平台的 manifest、Skill、bundle、测试和发布说明。
+- 平台专用 Skill 从当前 `skills/itpay/SKILL.md` 派生，但认证、路径和工具选择规则允许平台差异。
+- 通用业务规则不得四处手工修改；同步器每次更新时生成或校验通用段落。
+- 支付相关公共 Skill 默认只引导外部 Checkout；operator escape hatch 不作为推荐工作流。
+
+依赖：Step 1。
+
+### Step 3：加入仓库内验证
+
+每个平台至少验证：
+
+```text
+没有全局 itpay 命令
+不允许测试过程访问 npm registry
+bundle itpay --version == lock.version
+bundle itpay skill show itpay --json 成功
+平台 manifest 可被官方 validator/CLI 读取
+启动器路径含空格时仍可运行
+bundle 不包含凭据、.env、~/.itpay-v3 或 npm token
+```
+
+本地身份与网络业务测试使用临时 HOME；不得触碰开发者真实 `~/.itpay-v3`。
+
+依赖：Step 2。
+
+### Step 4：CLI 发布后创建同步 PR
+
+修改 CLI 主仓库现有 npm CD：只有 npm publish 成功或确认该 commit 已发布后，才向平台仓库发送带以下字段的事件：
+
+```json
+{
+  "version": "2.0.14",
+  "npm_integrity": "sha512-...",
+  "source_git_sha": "..."
+}
+```
+
+平台仓库收到事件后：
+
+- 重新生成 bundle；
+- 更新 manifest 版本、lock、changelog；
+- 跑全套测试；
+- 创建 `sync @itpay/cli X.Y.Z` PR；
+- PR 描述列出 CLI commit、integrity、平台测试和是否需要商店重新审核。
+
+增加每日一次的版本漂移检查作为丢失事件的兜底，只报警或补 PR，不直接发布。
+
+依赖：Step 3。
+
+### Step 5：平台发布和回滚
+
+- 合并同步 PR 后为平台仓库打与 manifest 一致的 tag。
+- OpenAI、Claude 官方市场和 WorkBuddy 按各自审核流程上传；Gemini GitHub Release 可由 tag 自动生成。
+- 保存每个平台已发布 CLI 版本矩阵。
+- 回滚通过重新发布上一个已验证 bundle 对应的平台版本，不修改或删除用户 Device 身份。
+
+依赖：Step 4。
+
+## 7. API / Data / Type Changes
+
+CLI 业务 API：无。
+
+新增发布合同：
+
+- `bundle.lock.json` schema。
+- CLI release dispatch payload。
+- 每个平台 manifest 和平台版本。
+
+CLI 版本和平台包版本第一阶段保持相同，减少映射成本。若以后平台仅修改说明而 CLI 未变，再引入独立的 `pluginVersion`，同时保留 `cliVersion`；现在不提前增加双版本系统。
+
+## 8. Tests / Verification
+
+### 自动化
+
+- bundle integrity、精确版本和依赖完整性。
+- 无全局 CLI、离线 smoke、路径含空格、Windows 启动。
+- Skill frontmatter/manifest 校验。
+- secret scan 和危险文件清单。
+- 发布矩阵与 npm 当前版本漂移检测。
+
+### 手动
+
+- 四个平台全新安装。
+- 同机存在全局旧版 CLI 时，Skill 仍调用 bundle 版本。
+- Skill 更新后 bundle 版本更新，但 `~/.itpay-v3/device` 未变化。
+- 平台卸载 Skill 后不删除用户已有 CLI Device 身份；是否保留平台专用缓存按平台规则处理。
+
+## 9. Risks / Uncertainties
+
+- OpenAI Skill 沙箱是否提供满足要求的 Node 运行时不能作为稳定合同；ChatGPT 路径应以远程 MCP 为主。
+- vendored `node_modules` 会增大包体，但当前依赖很少，先以真实平台大小限制验证，不提前引入 bundler。
+- 四个仓库意味着四套审核节奏，但不意味着四套 CLI 业务实现。
+- WorkBuddy 公共 SkillHub 提交通道未公开，自动化只能先生成可上传包。
+- 平台安全扫描可能拒绝支付或可执行 bundle；拒绝原因应反馈到相应平台仓库，不改变其他平台已通过版本。
+
+## 10. Checkpoint
+
+仓库创建和跨仓凭据配置属于外部状态操作。实施到该步骤时需要仓库组织名、创建权限和最小权限 GitHub App/PAT；在此之前可以完成生成器、模板和本地验证。