@yeying-community/web3-bs 1.0.16 → 1.0.17

package/docs/SDK/350/203/275/345/212/233.md

@@ -0,0 +1,272 @@
+# SDK能力
+
+本文档合并原有：
+- `SDK能力与账户管理设计.md`
+- `能力矩阵.md`
+- `库的定位与能力边界.md`
+
+目标：用一个文档同时回答“这是什么、怎么选路线、怎么落地接入”。
+
+## 1. 定位与边界
+
+`@yeying-community/web3-bs` 的定位是：
+
+> 浏览器端 DApp 连接、会话、认证、授权与存储接入 SDK
+
+更具体地说：
+- 以 EIP-1193 钱包为优先入口
+- 统一封装 Provider 发现、连接会话、SIWE 登录、UCAN 授权、中心化认证与 WebDAV 存储接入
+- 面向 DApp 前端集成，不承担后端鉴权逻辑
+
+它是什么：
+- 浏览器端前端集成 SDK
+- DApp 访问编排层（钱包 / App 钱包 / 中心化服务 / WebDAV）
+- 会话管理层（连接会话、认证会话、授权会话）
+
+它不是什么：
+- 不是链上交易构造与合约调用 SDK
+- 不是后端 UCAN/JWT 校验库
+- 不是 Node.js 服务端 SDK
+- 不是 WalletConnect / deep link / app bridge 本身
+
+实现边界：
+- 钱包协议语义由钱包仓库定义
+- audience / capability / app scope 由服务端定义
+- `web3-bs` 负责前端如何调用这些能力
+
+## 2. 路线与能力矩阵
+
+路线定义：
+- 钱包插件：浏览器内已安装插件钱包
+- App 钱包：钱包 App 或桥接层向前端暴露 Provider
+- 中心化服务：不依赖链上钱包，直接接中心化认证/授权
+
+| 能力 | 钱包插件 | App 钱包 | 中心化服务 | 说明 |
+| --- | --- | --- | --- | --- |
+| Provider 发现 | ✅ | ⚠️ | ❌ | `getProvider` 适合插件；App 钱包通常需要外部先注入/适配 |
+| 请求账户 | ✅ | ✅ | ❌ | 依赖 EIP-1193 `eth_requestAccounts` |
+| 标准消息签名 | ✅ | ✅ | ❌ | `signMessage` |
+| challenge / SIWE 登录 | ✅ | ✅ | ❌ | `loginWithChallenge` |
+| access token 缓存 / refresh | ✅ | ✅ | ✅ | `setAccessToken` / `authFetch` / `refreshAccessToken` |
+| 钱包用户名 / 邮箱授权 | ✅ | ❌ | ❌ | `connectAndGetWalletProfile` / `getWalletProfile` |
+| UCAN Session 创建 | ✅ | ⚠️ | ❌ | 优先 `yeying_ucan_session`；不可用时使用本地 session |
+| UCAN Root / Invocation | ✅ | ⚠️ | ❌ | Root 走 SIWE；Invocation 走 UCAN 签名 |
+| 多后端 UCAN 授权 | ✅ | ⚠️ | ❌ | 通过 delegation/invocation 按 audience/capability 下发 |
+| 中心化 session token | ✅ | ✅ | ✅ | `createCentralSession` |
+| 中心化 UCAN 签发 | ✅ | ✅ | ✅ | `issueCentralUcan` |
+| WebDAV 直接访问（JWT/UCAN） | ✅ | ✅ | ✅ | `createWebDavClient` |
+| WebDAV + UCAN 自动初始化 | ✅ | ⚠️ | ❌ | `initWebDavStorage` |
+| DApp 会话编排 | ✅ | ⚠️ | ❌ | `initDappSession` |
+| 加解密（站点授权后静默） | ✅ | ⚠️ | ❌ | `encrypt` / `decrypt` / `getSupportedCipherSuites`（钱包插件路线） |
+
+说明：
+- `✅`：天然支持
+- `⚠️`：可支持，但需要额外前提（尤其是 provider 适配或钱包能力）
+- `❌`：该路线下不成立或不是典型用法
+
+选型建议：
+- 已有浏览器插件：优先钱包插件路线
+- 移动端 Web 且可接 App 钱包：走 App 钱包路线
+- 更关注接入效率或无钱包条件：走中心化服务路线
+- 需要多后端统一授权：优先 UCAN 路线
+
+## 3. 账户与会话管理设计
+
+### 3.1 账户使用策略
+
+- 页面初始化先读取 `eth_accounts`，避免无意义弹窗
+- 用户主动点击连接时再调用 `eth_requestAccounts`
+- 优先复用“上次选择账户”，不存在时回退 `accounts[0]`
+
+示例：
+
+```ts
+import { getProvider, getPreferredAccount, watchProvider } from '@yeying-community/web3-bs';
+
+const stopProviderWatch = watchProvider(({ present }) => {
+  console.log('wallet provider present:', present);
+});
+
+const provider = await getProvider({ timeoutMs: 3000 });
+const { account } = await getPreferredAccount({
+  provider,
+  autoConnect: false,
+});
+```
+
+`requestAccounts` 默认会对同一 provider 的并发连接请求做去重。业务按钮仍建议在提交中展示 loading/disabled 状态，但 SDK 会避免重复点击直接触发多个 `eth_requestAccounts`。
+
+如果钱包确认窗口已经打开、但被其他页面遮挡，前端不应该继续盲目发起新的连接或签名请求，而应该优先把已有确认窗口拉回前台。为此 SDK 提供了 `focusPendingApproval`：
+
+```ts
+import { focusPendingApproval, requestAccounts } from '@yeying-community/web3-bs';
+
+const pending = await focusPendingApproval().catch(() => ({ focused: false }));
+if (!pending.focused) {
+  await requestAccounts();
+}
+```
+
+适用范围：
+- 钱包连接弹窗
+- 消息签名弹窗
+- 钱包解锁弹窗
+
+产品侧建议：
+- 用户重复点击“连接钱包 / 登录 / 签名确认”时，优先调用 `focusPendingApproval`
+- 只有在不存在待确认窗口时，才真正发起新的钱包 RPC
+- 这类逻辑应由 SDK 统一提供，业务应用只负责按钮状态与提示文案
+
+### 3.2 账户变更处理
+
+账户变化后建议清理认证与授权缓存，重新发起登录授权流程：
+
+```ts
+import { watchAccounts, clearAccessToken, clearUcanSession } from '@yeying-community/web3-bs';
+
+const unsubscribe = watchAccounts(provider, () => {
+  clearAccessToken({ storeToken: false });
+  clearUcanSession();
+});
+```
+
+### 3.3 三层会话模型
+
+- 连接会话：钱包连接状态与当前账户
+- 认证会话：SIWE/JWT 或中心化 token
+- 授权会话：UCAN Session、Root、Delegation、Invocation
+
+## 4. 登录与授权模型
+
+### 4.1 SIWE + JWT（单后端优先）
+
+典型流程：
+1. `POST /api/v1/public/auth/challenge`
+2. 钱包签名 challenge
+3. `POST /api/v1/public/auth/verify`
+4. 使用 access token 调用业务接口
+5. access 过期后 `POST /api/v1/public/auth/refresh`
+6. 退出时 `POST /api/v1/public/auth/logout`
+
+推荐 API 组合：
+- `loginWithChallenge`
+- `authFetch`
+- `refreshAccessToken`
+- `logout`
+
+### 4.2 UCAN（多后端授权）
+
+典型流程：
+1. `createUcanSession`
+2. `getOrCreateUcanRoot`（SIWE bridge）
+3. 可选 `createDelegationUcan`
+4. `createInvocationUcan`（按 audience + capability）
+5. `authUcanFetch` 访问目标后端
+
+说明：
+- Root 建议作为跨后端“统一授权根”
+- Invocation 作为短期令牌按后端和能力发放
+- Root 或 Invocation 过期后按链路重建
+- 发起长流式请求前，不只判断 token 未过期，还要判断剩余有效期是否足够支撑本次请求
+
+### 4.3 SIWE 与 UCAN 对比
+
+| 维度 | SIWE/JWT | UCAN |
+| --- | --- | --- |
+| Token 来源 | 后端签发 | 前端组装、后端校验 |
+| 主要场景 | 单后端登录 | 多后端能力委任 |
+| 续期方式 | refresh 接口 | 重建 invocation（必要时重建 root） |
+| 权限表达 | 后端角色/策略 | `with/can` capability |
+
+## 5. API 能力分组
+
+### 5.1 Provider 与钱包接入
+
+- `getProvider` / `requireProvider`
+- `requestAccounts` / `getAccounts` / `watchAccounts`
+- `getPreferredAccount`
+- `getChainId` / `getBalance`
+- `signMessage`
+
+### 5.2 SIWE 与 JWT
+
+- `loginWithChallenge`
+- `authFetch`
+- `refreshAccessToken`
+- `logout`
+- `getAccessToken` / `setAccessToken` / `clearAccessToken`
+
+### 5.3 UCAN 授权
+
+- `createUcanSession` / `getUcanSession`
+- `createRootUcan` / `getOrCreateUcanRoot`
+- `createDelegationUcan`
+- `createInvocationUcan` / `getOrCreateInvocationUcan`
+- `authUcanFetch`
+- `normalizeUcanCapabilities`
+- `getUcanTokenTiming` / `isUcanTokenFresh`
+- `classifyUcanAuthError`
+
+### 5.4 中心化 UCAN
+
+- `getCentralIssuerInfo`
+- `createCentralSession`
+- `issueCentralUcan`
+- `createAndIssueCentralUcan`
+- `authCentralUcanFetch`
+
+### 5.5 WebDAV 与会话编排
+
+- `createWebDavClient`
+- `createShareLink` / `listShareLinks` / `revokeShareLink`
+- `initWebDavStorage`
+- `initDappSession`
+- `deriveAppIdFromLocation` / `deriveAppIdFromHost`
+
+### 5.6 加解密服务
+
+- `encrypt` — 用命名安全套件加密（默认 `aes-256-gcm`）
+- `decrypt` — 解密 v1 格式密文
+- `getSupportedCipherSuites` — 列出可用套件
+- `CipherError` / `isUserRejectedWalletAction` — 错误分类
+
+详细用法、安全模型、限制见 [`加解密服务.md`](./加解密服务.md)。
+
+## 6. 推荐接入组合
+
+| 场景 | 推荐组合 |
+| --- | --- |
+| 插件钱包 + 单后端登录 | `getProvider` + `requestAccounts` + `loginWithChallenge` + `authFetch` |
+| 插件钱包 + UCAN 多后端 | `createUcanSession` + `getOrCreateUcanRoot` + `createInvocationUcan` |
+| App 钱包 + 登录 | `requestAccounts` + `signMessage` + `loginWithChallenge` + `authFetch` |
+| 中心化 JWT | `setAccessToken` + `authFetch` + `createWebDavClient` |
+| 中心化 UCAN | `createCentralSession` + `issueCentralUcan` + `authCentralUcanFetch` |
+| WebDAV 直接访问 | `createWebDavClient` |
+| WebDAV + UCAN 自动初始化 | `initWebDavStorage` |
+
+长请求建议：
+- 普通短请求使用默认 token skew 即可，skew 只用于判断是否自动换新 Invocation。
+- token 已过期或进入 skew 窗口时，应自动创建新的 Invocation，不应提前向用户报错。
+- 如果服务端仍返回 `UCAN expired` / 401，`authUcanFetch` 会在可重放请求体场景下自动刷新 Invocation 并重试一次。
+- 详见 [UCAN有效期与续期机制](./UCAN有效期与续期机制.md)。
+
+## 7. 工程与安全注意事项
+
+- 仅支持浏览器环境（依赖 `window` / `fetch` / `localStorage` / `IndexedDB`）
+- `baseUrl` 只填服务根地址，子路径放 `prefix`
+- capability 资源格式必须与目标服务定义一致（建议统一 `with/can`）
+- 多钱包支持不代表高级能力跨钱包完全等价，取决于钱包能力实现
+- 建议统一 `appId` 生成规则，避免 `localhost` 与 `127.0.0.1` 产生两套目录
+
+### 7.1 warehouse 分享链接授权边界
+
+- 在 UCAN 链路下，当 capability 使用 `app` scope（例如 `app:all:<appId>`）时，分享链接创建与查询仅允许落在该授权目录内。
+- 在 JWT 或未携带 UCAN `app` scope 的链路下，分享链接范围由后端鉴权策略决定，不自动继承 UCAN 的目录隔离语义。
+- 需要“只能创建/查询授权目录文件分享链接”的场景，建议统一走 UCAN `app` scope 授权。
+
+## 8. 相关阅读
+
+- [快速上手](./快速上手.md)
+- [UCAN有效期与续期机制](./UCAN有效期与续期机制.md)
+- [移动端认证与授权选型指南](./移动端认证与授权选型指南.md)
+- [开放接口规范](./开放接口规范.yaml)

package/docs/UCAN/346/234/211/346/225/210/346/234/237/344/270/216/347/273/255/346/234/237/346/234/272/345/210/266.md

@@ -0,0 +1,305 @@
+# UCAN有效期与续期机制
+
+本文档说明 `@yeying-community/web3-bs` 中 UCAN token 的有效期配置、过期判断和推荐续期策略。目标是让所有 DApp 使用同一套规则，而不是在各应用里各自硬编码。
+
+## 1. 核心原则
+
+`skew` 不是用来提前给用户报错的，而是用来判断“当前 Invocation Token 是否还值得复用”。
+
+只要 Root / Session 还有效，SDK 就应该自动生成新的 Invocation Token，用户不应该感知 Invocation 过期。
+
+用户真正需要重新操作的钱包授权，只应该发生在 Root / Session 过期、账户变化、能力不足或服务端拒绝继续授权时。
+
+## 2. 为什么要自动刷新重试
+
+只判断 token “当前还没过期”是不够的，但正确处理方式不是让业务自己预估请求耗时，而是让 SDK 统一处理过期后的刷新重试。
+
+典型问题：
+- 用户发起请求时，本地判断 token 仍有效。
+- 服务端因为时钟差、校验策略或处理过程中 token 过期，最终返回 `UCAN expired`。
+- 用户已经等待、上游可能已经消耗 token，但前端拿不到有效结果。
+
+正确策略分两层：
+- 请求前优化：用 `skew` 做很小的时钟安全提前量。如果 token 即将过期，就在请求发出前静默生成新的 Invocation Token。
+- 请求后兜底：如果服务端仍返回 `UCAN expired`，SDK 自动重新生成 Invocation Token 并重试一次。
+
+## 3. 有效期层次
+
+### 3.1 Root UCAN
+
+Root UCAN 是用户通过钱包签名建立的授权根。
+
+默认有效期：
+- `DEFAULT_UCAN_SESSION_TTL_MS`
+- 当前值：24 小时
+
+特点：
+- 通常需要用户钱包签名。
+- 过期后需要重新创建 Root。
+- 如果钱包签名窗口被遮挡，应用应通过 SDK 的钱包弹窗聚焦能力唤回，而不是重复发起多个签名请求。
+
+### 3.2 Local / Wallet UCAN Session
+
+UCAN Session 是用于签发 Delegation / Invocation 的会话密钥。
+
+默认有效期：
+- `DEFAULT_UCAN_SESSION_TTL_MS`
+- 当前值：24 小时
+
+来源：
+- 钱包支持 `yeying_ucan_session` 时，优先使用钱包托管 session。
+- 钱包不支持时，SDK 回退到本地 Ed25519 session，并保存在 IndexedDB。
+
+过期处理：
+- session 过期后 SDK 会重新创建。
+- 如果需要钱包参与，可能触发钱包交互。
+
+### 3.3 Delegation UCAN
+
+Delegation UCAN 用于把能力委托给另一个 audience。
+
+默认有效期：
+- `DEFAULT_UCAN_TOKEN_TTL_MS`
+- 当前值：40 分钟
+
+特点：
+- 适合短期委托。
+- 过期后可在 Root 和 Session 仍有效时重新签发。
+
+### 3.4 Invocation UCAN
+
+Invocation UCAN 是真正发给目标服务的短期调用 token。
+
+默认有效期：
+- `DEFAULT_UCAN_TOKEN_TTL_MS`
+- 当前值：40 分钟
+
+默认时钟偏移：
+- `DEFAULT_UCAN_TOKEN_SKEW_MS`
+- 当前值：1 分钟
+
+特点：
+- 应按 audience + capability 生成。
+- 应短期有效，降低泄漏风险。
+- 请求前如果进入 `skew` 窗口，SDK 应自动重新生成 Invocation Token。
+- 正常情况下，Invocation Token 过期不应该打断用户正在发起的新请求。
+
+### 3.5 中心化 UCAN / 中心化 Session
+
+中心化 UCAN 由中心化服务签发。
+
+特点：
+- 有效期由中心化服务返回值决定。
+- 前端仍应使用 SDK 的 token timing 工具判断是否足够支撑请求。
+- 如果中心化 session 过期，需要走中心化 session 续期或重新登录。
+
+## 4. SDK 默认值
+
+| 常量 | 默认值 | 用途 |
+| --- | --- | --- |
+| `DEFAULT_UCAN_SESSION_TTL_MS` | 24 小时 | Root / Session 默认有效期 |
+| `DEFAULT_UCAN_TOKEN_TTL_MS` | 40 分钟 | Delegation / Invocation 默认有效期 |
+| `DEFAULT_UCAN_TOKEN_SKEW_MS` | 1 分钟 | 判断 Invocation 是否需要换新的安全提前量 |
+
+## 5. SDK 提供的通用能力
+
+### 5.1 解析 token timing
+
+```ts
+import { getUcanTokenTiming } from '@yeying-community/web3-bs';
+
+const timing = getUcanTokenTiming(ucan);
+
+console.log(timing.valid);
+console.log(timing.remainingMs);
+console.log(timing.exp);
+console.log(timing.nbf);
+```
+
+适用场景：
+- UI 展示授权剩余时间。
+- 请求前判断 token 是否仍可用。
+- 调试 UCAN 过期问题。
+
+### 5.2 判断 token 是否新鲜
+
+```ts
+import { isUcanTokenFresh } from '@yeying-community/web3-bs';
+
+const ok = isUcanTokenFresh(ucan, {
+  skewMs: 5_000,
+});
+
+if (!ok) {
+  // 自动重新签发 invocation token 后再请求
+}
+```
+
+通常不需要手动传 `skewMs`，使用 SDK 默认值即可。
+
+### 5.3 自动获取可用 Invocation Token
+
+业务应用优先使用 `getOrCreateInvocationUcan`，而不是自己判断后报错：
+
+```ts
+import { getOrCreateInvocationUcan } from '@yeying-community/web3-bs';
+
+const ucan = await getOrCreateInvocationUcan({
+  ucan: cachedInvocationToken,
+  issuer: session,
+  audience: 'did:web:router.example.com',
+  capabilities: [{ with: 'app:all:chat', can: 'invoke' }],
+  proofs: [root],
+});
+```
+
+行为：
+- 如果 `cachedInvocationToken` 仍足够新鲜，直接复用。
+- 如果剩余有效期不足，自动创建新的 Invocation Token。
+- 如果 Session / Root 仍有效，这个过程不需要用户重新签名。
+- 如果 Session / Root 已失效，才进入重新授权流程。
+
+### 5.4 过期后自动刷新重试
+
+`authUcanFetch` 会在可安全重试时自动处理 Invocation 过期：
+
+```ts
+import { authUcanFetch } from '@yeying-community/web3-bs';
+
+const response = await authUcanFetch(
+  'https://api.example.com/protected',
+  {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ message: 'hello' }),
+  },
+  {
+    issuer: session,
+    audience: 'did:web:api.example.com',
+    capabilities: [{ with: 'app:all:chat', can: 'invoke' }],
+    proofs: [root],
+  }
+);
+```
+
+行为：
+- 第一次请求如果成功，直接返回。
+- 如果服务端返回可识别的 `UCAN expired` / 401，SDK 强制创建新的 Invocation Token。
+- SDK 使用新的 Invocation Token 自动重试一次。
+- 如果 Root / Session 仍有效，整个过程用户无感。
+- 如果请求体是不可重放的流式 body，SDK 不会自动重试，避免重复消费 body。
+
+这才是过期体验的主要兜底机制。
+
+### 5.5 分类 UCAN 认证错误
+
+```ts
+import { classifyUcanAuthError } from '@yeying-community/web3-bs';
+
+const info = classifyUcanAuthError(error);
+
+if (info.shouldRefresh) {
+  // 刷新或重建 token
+}
+```
+
+可识别类型：
+- `expired`
+- `not-before`
+- `unauthorized`
+- `forbidden`
+- `invalid-token`
+- `unknown`
+
+`UCAN expired (trace id: xxx)` 会被识别为：
+
+```ts
+{
+  type: 'expired',
+  retryable: true,
+  shouldRefresh: true
+}
+```
+
+## 6. WebDAV 自动初始化中的有效期配置
+
+`initWebDavStorage` 支持为 invocation token 配置有效期和 skew：
+
+```ts
+import { initWebDavStorage } from '@yeying-community/web3-bs';
+
+const storage = await initWebDavStorage({
+  baseUrl: 'https://webdav.example.com',
+  prefix: '/dav',
+  audience: 'did:web:webdav.example.com',
+  appId,
+  capabilities: [{ with: `app:all:${appId}`, can: 'write' }],
+  invocationExpiresInMs: 40 * 60 * 1000,
+});
+```
+
+行为：
+- 如果缓存 token 已过期或进入 skew 窗口，SDK 会重新签发 invocation token。
+- 如果 Root / Session 仍有效，重新签发不需要用户重新签名。
+- 如果 Root / Session 已过期，才需要走更上层的授权重建。
+
+## 7. 推荐配置
+
+| 场景 | Invocation TTL | 请求前判断 | 说明 |
+| --- | --- | --- | --- |
+| 普通接口请求 | 默认 40 分钟 | 默认 skew 即可 | 正常情况下无感复用或换新 |
+| WebDAV 小文件读写 | 默认 40 分钟 | 默认 skew 即可 | 过期后由 SDK 自动刷新重试 |
+| AI 流式对话 | 默认 40 分钟 | 默认 skew 即可 | 过期后由 SDK 自动刷新重试；极长任务应使用任务 ID 恢复 |
+| 长任务 / 批量任务 | 默认 40 分钟或按需更长 | 默认 skew 即可 | 如果任务极长，应改为服务端任务票据 |
+
+## 8. DApp 集成建议
+
+请求前：
+- 使用 SDK 默认 skew 判断是否复用旧 Invocation。
+- 如果 token 已过期或即将过期，SDK 应静默刷新或重建 Invocation。
+- 不要只用 `exp > now` 判断，更不要把“剩余有效期不足”直接暴露成用户错误。
+
+请求中：
+- 流式请求开始后不要频繁重试同一请求，避免重复消耗。
+- 如果服务端支持任务 ID，应优先恢复任务结果，而不是重新执行。
+
+请求失败后：
+- 使用 `classifyUcanAuthError` 判断错误。
+- `expired` / `invalid-token` / `unauthorized` 可以刷新 Invocation 后重试一次。
+- `forbidden` 通常是能力不足，不应盲目重试。
+
+账户变化后：
+- 清理 access token。
+- 清理 UCAN session。
+- 重新建立 Root / Session / Invocation。
+
+## 9. 产品体验建议
+
+用户不应该看到“token 过期导致本次请求失败但已经消耗资源”的结果。
+
+推荐体验：
+- 请求前静默检查 token 是否过期或即将过期。
+- token 已过期或即将过期时静默刷新 Invocation。
+- 需要钱包签名时，明确提示用户“需要重新授权”。
+- 钱包弹窗被遮挡时，重复点击只聚焦已有弹窗，不重复发起签名。
+- 长流式请求失败后，如果能通过任务 ID 恢复结果，优先恢复；否则再提示用户重试。
+
+## 10. 服务端配合要求
+
+服务端应返回可分类的错误信息：
+
+```json
+{
+  "error": {
+    "message": "UCAN expired",
+    "type": "auth_error",
+    "code": "UCAN_EXPIRED"
+  }
+}
+```
+
+建议：
+- 401：认证缺失、token 无效、token 过期。
+- 403：认证有效但 capability 不足。
+- 错误 message 或 code 中明确包含 `UCAN_EXPIRED` / `UCAN_INVALID` / `UCAN_FORBIDDEN`。
+- 长任务接口尽量返回任务 ID，避免前端因网络或 token 过期重复消耗。