@itpay/cli 2.0.13 → 2.0.15

package/docs/cli-reference/commands/refund/watch.md

@@ -1,5 +1,7 @@
 # `itpay refund watch`
 
+> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. Under that one product entry point, the two top-level commerce actions are `buy` and `sell`: Buyer workflows are available now; Seller workflows will use the same entry point and are not implemented yet.
+
 ## 范围与意义
 
 轮询同一退款直到终态或 timeout。命令内部可以读取多次，但对外只输出一个最终信封，不把无变化轮询刷入 Agent 上下文。中断后可无副作用重跑。

package/docs/cli-reference/commands/services/action.md

@@ -1,5 +1,7 @@
 # `itpay services action`
 
+> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. Under that one product entry point, the two top-level commerce actions are `buy` and `sell`: Buyer workflows are available now; Seller workflows will use the same entry point and are not implemented yet.
+
 ## 范围与意义
 
 记录用户或 Agent 对 Service Execution 的结构化动作，例如选择候选、批准、拒绝或取消。它不直接调用付费 Provider。

package/docs/cli-reference/commands/services/checkout.md

@@ -1,5 +1,7 @@
 # `itpay services checkout`
 
+> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. Under that one product entry point, the two top-level commerce actions are `buy` and `sell`: Buyer workflows are available now; Seller workflows will use the same entry point and are not implemented yet.
+
 ## 范围与意义
 
 为单个 Service Execution 快速创建或恢复 Checkout，并按 Host 向人交接付款入口。它是 `services quote -> cart add --quote -> buy --cart` 的单项快捷方式，必须复用相同的 Quote、Cart 和 Checkout Use Case。

package/docs/cli-reference/commands/services/events.md

@@ -1,5 +1,7 @@
 # `itpay services events`
 
+> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. Under that one product entry point, the two top-level commerce actions are `buy` and `sell`: Buyer workflows are available now; Seller workflows will use the same entry point and are not implemented yet.
+
 ## 范围与意义
 
 按 sequence 升序读取一笔 Service Execution 的受限诊断事件。它只用于解释异常或支持排查，不是正常业务流程，不返回事件 ID、内部摘要、Provider 数据或受保护交付内容。

package/docs/cli-reference/commands/services/get.md

@@ -1,5 +1,7 @@
 # `itpay services get`
 
+> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. Under that one product entry point, the two top-level commerce actions are `buy` and `sell`: Buyer workflows are available now; Seller workflows will use the same entry point and are not implemented yet.
+
 ## 范围与意义
 
 读取一笔 Service Execution 的紧凑状态、关键节点和当前首选动作。它面向恢复和用户解释，不是原始 event dump。

package/docs/cli-reference/commands/services/index.md

@@ -1,5 +1,7 @@
 # `itpay services`
 
+> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. Under that one product entry point, the two top-level commerce actions are `buy` and `sell`: Buyer workflows are available now; Seller workflows will use the same entry point and are not implemented yet.
+
 ## 命令范围
 
 操作通用 Service Execution。CLI 不知道某个服务的业务流程；它读取服务合同中的 capability、input schema、价格、交付模式和服务端 next action。

package/docs/cli-reference/commands/services/invoke.md

@@ -1,5 +1,7 @@
 # `itpay services invoke`
 
+> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. Under that one product entry point, the two top-level commerce actions are `buy` and `sell`: Buyer workflows are available now; Seller workflows will use the same entry point and are not implemented yet.
+
 ## 范围与意义
 
 调用当前 phase 允许的非付费 Agent-visible capability。输入先按 capability schema 校验，校验失败不得迁移 execution 或记录 Provider 已调用。

package/docs/cli-reference/commands/services/list.md

@@ -1,5 +1,7 @@
 # `itpay services list`
 
+> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. Under that one product entry point, the two top-level commerce actions are `buy` and `sell`: Buyer workflows are available now; Seller workflows will use the same entry point and are not implemented yet.
+
 ## 范围与意义
 
 恢复当前已登记设备或账号可见的 Service Execution 摘要。它不是批量 timeline 导出。

package/docs/cli-reference/commands/services/next.md

@@ -1,5 +1,7 @@
 # `itpay services next`
 
+> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. Under that one product entry point, the two top-level commerce actions are `buy` and `sell`: Buyer workflows are available now; Seller workflows will use the same entry point and are not implemented yet.
+
 ## 范围与意义
 
 读取一笔 Service Execution 的当前状态，并只返回一个首选下一步。若交付模式允许 Agent 直接读取，本命令同时返回完整 safe result。

package/docs/cli-reference/commands/services/quote.md

@@ -1,5 +1,7 @@
 # `itpay services quote`
 
+> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. Under that one product entry point, the two top-level commerce actions are `buy` and `sell`: Buyer workflows are available now; Seller workflows will use the same entry point and are not implemented yet.
+
 ## 范围与意义
 
 为当前 Service Execution 的一个付费 Capability 准备 Quote Lock。它只锁定可信输入、候选来源、价格、币种和有效期，不创建 Cart、Checkout、订单或 Provider 调用。

package/docs/cli-reference/commands/services/read-result.md

@@ -1,5 +1,7 @@
 # `itpay services read-result`
 
+> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. Under that one product entry point, the two top-level commerce actions are `buy` and `sell`: Buyer workflows are available now; Seller workflows will use the same entry point and are not implemented yet.
+
 ## 范围与意义
 
 使用当前 Agent Device Authority，在用户创建的有效、未过期且范围匹配的 grant 内读取 Vault 保护结果。它不适用于 `agent_visible_result`。

package/docs/cli-reference/commands/services/start.md

@@ -1,5 +1,7 @@
 # `itpay services start`
 
+> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. Under that one product entry point, the two top-level commerce actions are `buy` and `sell`: Buyer workflows are available now; Seller workflows will use the same entry point and are not implemented yet.
+
 ## 范围与意义
 
 按 Catalog 中的 `service_id` 启动一次 Service Execution，并返回当前可执行的唯一首选动作。不会调用 Provider、创建 Checkout 或订单。

package/docs/cli-reference/commands/skill.md

@@ -1,14 +1,16 @@
 # `itpay skill show`
 
+> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. Under that one product entry point, the two top-level commerce actions are `buy` and `sell`: Buyer workflows are available now; Seller workflows will use the same entry point and are not implemented yet.
+
 ## 范围与意义
 
-读取 npm 包内置的完整 Agent Skill。与按 topic 渐进读取的 `docs` 不同，本命令故意一次返回完整 `SKILL.md`，用于首次 onboarding 和身份/session 规则恢复；不访问 Backend，不修改宿主配置或本地身份。
+读取 npm 包内置的完整 ItPay Agent Skill。与按 topic 渐进读取的 `docs` 不同，本命令故意一次返回完整 `SKILL.md`，用于首次 onboarding 和身份/session 规则恢复；不访问 Backend，不修改宿主配置或本地身份。
 
 ```bash
-itpay [--agent-type <agent_type>] skill show itpay-buyer [--json]
+itpay [--agent-type <agent_type>] skill show itpay [--json]
 ```
 
-当前只内置 `itpay-buyer`。`--json` 时完整 Markdown 位于 `result.content`；文本模式直接输出完整内容。
+当前只内置 `itpay`。该 Skill 是 Buyer 与未来 Seller 的共同入口，不再按角色拆分名称。`--json` 时完整 Markdown 位于 `result.content`；文本模式直接输出完整内容。
 
 未声明 Agent Type 时，`next` 是 `itpay install --json`。已声明时，`next` 是保留同一类型的 `catalog list --json`。未知名称返回 `skill_not_found`；包内文件缺失或损坏返回 `skill_unavailable` 并要求重装同版本 CLI。
 

package/docs/cli-reference/conventions.md

@@ -1,5 +1,7 @@
 # Output And Error Contract
 
+> **Product boundary:** `itpay` is the single public CLI entry point, and `$itpay` is its user-facing Skill invocation. Under that one product entry point, the two top-level commerce actions are `buy` and `sell`: Buyer workflows are available now; Seller workflows will use the same entry point and are not implemented yet.
+
 ## 目标
 
 CLI 输出是给 Agent 执行的协议，不是后端 DTO 的调试转储。默认输出适合人阅读；`--json` 使用同一语义的稳定机器合同。调试事实只由明确的诊断命令返回。

package/docs/cli-reference/index.md

@@ -2,6 +2,8 @@
 
 本目录是 ItPay CLI 的规范性命令合同。它定义命令应向人和 Agent 返回什么、如何指导下一步，以及失败后如何恢复。当前实现与本文档不一致时，以本文档作为后续校准目标。
 
+> **统一产品边界：** `itpay` 是唯一公开的 CLI 入口，`$itpay` 是对应的用户侧 Skill 调用方式。在同一个产品入口下，两个顶层 commerce 动作是 `buy` 和 `sell`：Buyer 流程当前可用；Seller 流程未来仍使用同一入口，当前尚未实现。不得拆分出独立 Buyer 或 Seller 产品入口。
+
 企知道可以作为示例数据出现，但任何命令、字段、状态和 instruction 都不得依赖某个服务。服务差异只能来自 Catalog、Service Contract、Capability metadata 和服务端状态。
 
 ## 使用约定
@@ -21,7 +23,7 @@
 - [`itpay catalog`](commands/catalog/index.md)
   - [`itpay catalog list`](commands/catalog/list.md)
 - [`itpay install`](commands/install.md) - 查看指定 Agent 的安装说明
-- [`itpay skill show`](commands/skill.md) - 一次读取完整内置 Buyer Skill
+- [`itpay skill show`](commands/skill.md) - 一次读取完整内置 ItPay Skill
 - [`itpay docs`](commands/docs/index.md)
   - [`itpay docs list`](commands/docs/list.md)
   - [`itpay docs show`](commands/docs/show.md)

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 传递方式。