@itpay/cli 2.0.25 → 2.0.27

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

@@ -1,256 +1,134 @@
-# 核心任务一：MCP 专用认证系统
+# Local Device 与远程 MCP OAuth 边界
 
-状态：待实施
+状态：current boundary；服务端实现以 `itpay-ai/compose` 为准。
+最后核对：2026-08-10。
 
-## 1. Current State
+## 1. 本文负责什么
 
-### CLI Device Authority
+本文只定义 CLI/平台包必须遵守的身份选择和凭据保管规则。
 
-当前 `src/state/device_authority.ts`：
+服务端 OAuth 协议、Connection、workload delegation、Buyer 和 Vault 数据
+模型由 Compose 仓库的 V3 文档、Schema、OpenAPI 和代码负责。CLI 仓库不再
+维护一份重复的 OAuth Server 实施计划。
 
-- 每个本地安装生成一把 Ed25519 私钥。
-- 私钥和 Device 状态存放在 `~/.itpay-v3/device`，owner-only 权限。
-- 一个 production Device registration 下按 `agent_type` 建立 Agent Instance。
-- CLI 通过 challenge 签名取得短期 Device session。
-- 受保护请求使用 `Authorization: ItPayDevice ...` 加请求签名。
-- session 失效只续期一次；已撤销的 v2 registration 不会静默替换。
+## 2. Local Device Authority
 
-这套系统回答的是“哪个本地 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 通道：
+本地 CLI 使用：
 
 ```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
+~/.itpay-v3/device/device-private.pem
+~/.itpay-v3/device/identity.json
 ```
 
-完成后：
-
-- 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 与用户账号的可选显式关联。
-- 审计日志、最小化返回、测试账号和平台审核所需演示凭据。
+`src/state/device_authority.ts`：
 
-### Out of scope
+- 生成/保存本地 Ed25519 私钥；
+- 按 Backend base URL 保持独立 Device registration；
+- 按显式 Agent Type 解析 exact Agent Instance；
+- 用 challenge 签名取得短期 Device Session；
+- 对受保护请求签名并防重放；
+- 只对可恢复 session 执行一次续期和同请求重放；
+- 不静默替换被吊销 Device。
 
-- 重写 CLI Device Authority。
-- 让 MCP 读取或迁移本地 Device 私钥。
-- 让平台 Access Token 代替支付确认。
-- 在聊天内容中采集支付卡、支付密码、验证码、钱包私钥。
-- 为每个平台建立独立 ItPay 用户表。
+这些文件表示本地工作负载，不表示网页登录 Token，也不能被复制进平台
+bundle。
 
-## 4. 认证边界
+## 3. 远程 MCP OAuth
 
-### 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，不做静默降级。
-
-### 服务端身份关系
-
-建议关系而非第二套用户系统：
+云端 MCP 客户端使用标准 OAuth Connection：
 
 ```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
+MCP client
+-> Authorization Code + PKCE
+-> ItPay login/consent
+-> client stores Access/Refresh Token
+-> ItPay MCP validates token
+-> exact MCP Connection
+-> Buyer-less workload delegation to Backend
 ```
 
-Access token 的 `sub` 是稳定、不可猜测的 ItPay 用户 subject。若需要减少跨客户端关联，应使用 pairwise subject，并在服务端映射回同一 `user_id`；不要把 email、ChatGPT 用户名或平台会话 ID 当主键。
-
-## 5. Implementation Steps
-
-### Step 1：冻结现有 CLI 认证合同
+平台客户端负责 Token 持久化、刷新和断线重连。以下位置都不能保存或打印
+OAuth Token：
 
-依赖：无。
+- CLI；
+- `~/.itpay-v3`；
+- Skill / Plugin；
+- `bundle.lock.json`；
+- 模型提示、tool 参数或 tool 输出；
+- Git 仓库；
+- Backend 普通 API 日志。
 
-- 为现有 Device enrollment、session、请求签名、401 单次恢复补齐合同测试。
-- 记录 Device API 可访问的路由集合。
-- 确认 MCP 改动不会修改 `src/state/device_authority.ts` 的持久化 schema。
+十分钟 Access Token 到期应由 Refresh Token 自动续期，不得让用户每十分钟
+重新扫码。Vault 短期授权到期是独立事件，只重新请求 Vault 授权。
 
-完成条件：加入 MCP 中间件前后，现有 CLI 测试结果和本地身份文件保持一致。
+## 4. 两条线路不能混用
 
-### Step 2：定义 OAuth issuer 和 MCP resource
+| 属性 | Local CLI | Remote MCP |
+| --- | --- | --- |
+| caller | Device + exact Agent Instance | exact MCP Connection |
+| credential owner | 用户本机 CLI | MCP client/platform |
+| Authorization | `ItPayDevice` + signed headers | OAuth Bearer at MCP resource |
+| server hop | CLI -> Backend | Platform -> MCP -> delegated Backend |
+| durable revoke | Device/Agent | Connection/Grant |
+| Buyer relationship | explicit Device binding | OAuth Connection binding |
 
-依赖：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。
+- Backend Device middleware 不接受 MCP Bearer；
+- MCP resource 不接受 Device Session；
+- CLI 不读取 MCP Token；
+- MCP 不读取 `~/.itpay-v3`；
+- 撤销一个通道不删除另一个通道；
+- 两个通道可指向同一 Buyer，但 Vault 临时授权按 exact audience 分开。
 
-完成条件：平台可以发现授权端点，redirect URI 不能通配，code 只能使用一次且短期有效。
+## 5. 平台路由
 
-### Step 3：实现登录、同意和 token 生命周期
+平台 Skill 在开始业务动作前选择线路：
 
-依赖：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：无计划变更。
+```text
+persistent local shell and bundled CLI and no explicit MCP -> CLI
+pure cloud -> MCP
+explicit MCP request -> MCP
+explicit CLI request -> CLI
+```
 
-## 7. Tests / Verification
+同一任务不能：
 
-### 单元测试
+- 同时调用两条线路；
+- 在失败后静默 fallback；
+- 用 email、昵称、Agent Type 或平台名推断 Buyer；
+- 用 Device/MCP 重连重置免费额度或资源归属。
 
-- PKCE verifier、redirect URI、state、code 单次消费。
-- issuer/audience/scope/expiry/signature/revocation。
-- refresh rotation 和旧 token 重放。
-- Device/Bearer scheme 互相拒绝。
+## 6. 跨平台 Buyer Vault 读取
 
-### 集成测试
+Local Device 与 MCP Connection 可以读取同一 Buyer Vault，但必须分别完成：
 
-- 完整 OAuth 登录、MCP 调用、刷新、撤销。
-- 同一 ItPay 用户从两个平台 client 登录。
-- MCP OAuth 登录后，本地 CLI Device ID 和私钥 hash 不变。
-- Device 撤销后 MCP grant 仍按自身状态工作；反向亦然。
-- 订单、Checkout、退款的跨用户越权测试。
+1. durable caller authentication；
+2. exact-audience temporary Vault window；
+3. 对需要首次揭示的工件完成 artifact-specific consent。
 
-### 手动验证
+CLI/MCP 连接不等于持续读取授权，OAuth 登录也不等于首次揭示或退款授权。
 
-- ChatGPT Connect/Disconnect。
-- 另一个支持远程 MCP OAuth 的平台连接。
-- 本地 CLI 同时运行并完成 `readyz`、目录、Checkout 恢复。
+最终产品、API、Schema 和测试合同由 Compose 文档
+`V3_CROSS_PLATFORM_BUYER_VAULT_READ_IMPLEMENTATION_PLAN.md` 负责。
 
-## 8. Risks / Uncertainties
+## 7. 平台不兼容时
 
-- MCP 服务端代码不在当前 CLI 仓库，本文件定义合同，实施前必须在对应服务端仓库重新追踪现有用户/session 模块。
-- 各平台对动态 client registration、redirect URI 和 token metadata 的细节可能不同；以平台实际连接测试为准。
-- OpenAI 对金融交易和 PCI 数据有额外限制。MCP 只编排外部 Checkout，不把 OAuth 登录等同于付款授权。
-- `ITPAY_BEARER_TOKEN` 的长期定位需要服务端确认；第一版不删除、不重命名，也不让 MCP 依赖该环境变量。
+如果平台不能安全完成标准 OAuth 或保存/刷新 Token：
 
-## 9. Checkpoint
+- 有本地 Shell 时使用 bundled CLI；
+- 没有本地 Shell 时标记 MCP 不支持；
+- 不接受静态 personal bearer；
+- 不要求用户在聊天中粘贴 Token；
+- 不把 Token做成普通 Skill setting。
 
-本任务不需要改动当前 CLI 身份即可开始。实施时只有以下情况停下确认：
+## 8. 验证门禁
 
-- 现有服务端没有可复用的 ItPay 用户主表；
-- 必须改变 Device principal 或 quota 归属；
-- 需要引入新的支付授权行为；
-- 平台要求与这里冲突的 token 传递方式。
+- CLI 升级前后 Device ID 和私钥 hash 不变；
+- MCP 连接/刷新/撤销不修改 Local Device 文件；
+- Device 与 MCP auth scheme 互相拒绝；
+- 两个 Connection 与两个 Agent Instance 的 Vault audience 相互隔离；
+- Access Token 刷新无需用户或模型参与；
+- Vault window 到期不会销毁 OAuth/Device durable identity；
+- 日志、bundle、tool output 和 repo secret scan 无凭据；
+- 平台失败时没有静默线路切换。