@yeying-community/web3-bs 1.0.16 → 1.0.17

package/docs//345/277/253/351/200/237/344/270/212/346/211/213.md

@@ -0,0 +1,476 @@
+# 快速上手
+
+本文档按 3 条接入路线来组织：
+
+1. 钱包插件路线
+2. App 钱包路线
+3. 中心化服务路线
+
+目标不是罗列全部 API，而是让 DApp 团队先判断“我该走哪条路”，再落到对应的代码组合。
+
+## 1. 安装
+
+```bash
+npm install @yeying-community/web3-bs
+```
+
+## 2. 先选路线
+
+### 2.1 钱包插件路线
+
+适合：
+- PC Web 为主
+- 浏览器里已有钱包插件
+- 需要标准连接、签名、SIWE 登录
+- 若需要 UCAN 多后端授权，优先走钱包 UCAN RPC；不支持时 SDK 会回退本地 Ed25519 session
+
+### 2.2 App 钱包路线
+
+适合：
+- 移动端 Web
+- 没有浏览器插件，但可以连接钱包 App
+- 钱包 App 或适配层能暴露 EIP-1193 能力
+
+### 2.3 中心化服务路线
+
+适合：
+- 无钱包、无插件，或者不要求链上身份
+- 希望统一用中心化会话、JWT 或中心化 UCAN
+- 目标是降低移动端接入成本
+
+## 3. 路线一：钱包插件
+
+这是当前最完整、最自然的路线。
+
+### 3.1 前提
+
+- 浏览器内有可用插件钱包
+- 至少支持 EIP-1193
+- 若要走 UCAN，多后端授权链路要求可完成 SIWE 签名（Root），session 签名优先用钱包 UCAN RPC：
+  - `yeying_ucan_session`（可选，优先）
+  - `yeying_ucan_sign`（可选，优先）
+  - 若 RPC 不可用，`web3-bs` 自动回退本地 Ed25519 session key（浏览器端 IndexedDB 持久化）
+
+### 3.2 典型流程图
+
+```text
+Detect Provider -> Request Accounts -> Sign / Login -> Access API -> Access WebDAV
+```
+
+### 3.3 适用钱包
+
+- YeYing：支持标准连接 + 钱包托管 UCAN session/sign
+- MetaMask 等 EIP-1193 钱包：支持连接、签名、challenge/SIWE 登录；UCAN session/sign 可走 SDK 本地回退
+
+关键边界：
+- “支持插件钱包”不等于“所有插件都支持 UCAN”
+- 通用插件至少可走标准签名 / JWT 登录
+- UCAN 路径优先使用钱包 UCAN RPC，不支持时可走 SDK 本地 session 回退
+
+### 3.4 最短接入：只做连接与签名
+
+```ts
+import { getProvider, requestAccounts, signMessage } from '@yeying-community/web3-bs';
+
+const provider = await getProvider({ preferYeYing: true });
+if (!provider) throw new Error('No injected wallet provider');
+
+const accounts = await requestAccounts({ provider });
+const address = accounts[0];
+if (!address) throw new Error('No account available');
+
+const signature = await signMessage({
+  provider,
+  address,
+  message: 'hello web3-bs',
+});
+```
+
+需要用户名或邮箱时，应在账户连接后按字段申请钱包资料权限：
+
+```ts
+import { connectAndGetWalletProfile } from '@yeying-community/web3-bs';
+
+const profile = await connectAndGetWalletProfile({
+  provider,
+  fields: ['username', 'email'],
+});
+
+console.log(profile.address, profile.profile);
+```
+
+完整授权生命周期、错误处理与隐私要求见[钱包资料授权](./钱包资料授权.md)。
+
+推荐用途：
+- 登录前置连接
+- 简单签名授权
+- 账户选择与账户变更监听
+
+### 3.5 插件钱包常规路线：challenge / SIWE 登录 + JWT
+
+这条路适用于所有标准 EIP-1193 钱包。
+
+```ts
+import {
+  loginWithChallenge,
+  authFetch,
+  refreshAccessToken,
+} from '@yeying-community/web3-bs';
+
+const login = await loginWithChallenge({
+  baseUrl: 'https://api.example.com/api/v1/public/auth',
+});
+
+const profileRes = await authFetch(
+  'https://api.example.com/api/v1/public/profile',
+  { method: 'GET' },
+  { baseUrl: 'https://api.example.com/api/v1/public/auth' }
+);
+
+const refreshed = await refreshAccessToken({
+  baseUrl: 'https://api.example.com/api/v1/public/auth',
+});
+```
+
+这条路线下，SDK 负责维护：
+- access token 缓存
+- refresh 流程
+- `authFetch` 的统一请求行为
+
+### 3.6 UCAN 路线：一次授权多个后端
+
+这条路优先使用钱包 UCAN RPC；若钱包不支持，SDK 会自动回退本地 UCAN session。
+
+```ts
+import {
+  createDelegationUcan,
+  createUcanSession,
+  getOrCreateUcanRoot,
+  createInvocationUcan,
+  authUcanFetch,
+  deriveAppIdFromLocation,
+} from '@yeying-community/web3-bs';
+
+const provider = await getProvider({ preferYeYing: true });
+if (!provider) throw new Error('No injected wallet provider');
+
+const appId = deriveAppIdFromLocation(window.location) || 'localhost-8001';
+const scope = `app:all:${appId}`;
+
+const session = await createUcanSession({ provider });
+
+const root = await getOrCreateUcanRoot({
+  provider,
+  session,
+  capabilities: [{ with: scope, can: 'invoke' }],
+});
+
+const delegateSession = await createUcanSession({ provider, id: 'demo-delegate' });
+const delegation = await createDelegationUcan({
+  issuer: session,
+  audience: delegateSession.did,
+  capabilities: [{ with: scope, can: 'invoke' }],
+  proofs: [root],
+});
+
+const ucan = await createInvocationUcan({
+  issuer: delegateSession,
+  audience: 'did:web:api.example.com',
+  capabilities: [{ with: scope, can: 'invoke' }],
+  proofs: [delegation],
+});
+
+const res = await authUcanFetch(
+  'https://api.example.com/api/v1/public/profile',
+  { method: 'GET' },
+  { ucan }
+);
+```
+
+这条路线下，SDK 负责维护：
+- UCAN session 读取与创建
+- Root proof 复用
+- Delegation / Invocation 证明链组装
+- Invocation token 缓存
+- 面向多个后端的 audience/capability 组装
+
+### 3.7 插件钱包下的 WebDAV
+
+#### 用 JWT 或 UCAN token 直接访问
+
+```ts
+import { createWebDavClient, deriveAppIdFromLocation } from '@yeying-community/web3-bs';
+
+const appId = deriveAppIdFromLocation(window.location) || 'localhost-8001';
+
+const client = createWebDavClient({
+  baseUrl: 'https://webdav.example.com',
+  prefix: '/dav',
+  token: '<JWT_OR_UCAN>',
+});
+
+await client.upload(`/apps/${appId}/hello.txt`, 'Hello WebDAV');
+```
+
+#### 用 UCAN 自动初始化存储
+
+```ts
+import { initWebDavStorage, deriveAppIdFromLocation } from '@yeying-community/web3-bs';
+
+const appId = deriveAppIdFromLocation(window.location) || 'localhost-8001';
+
+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' }],
+});
+
+await storage.client.upload(`${storage.appDir}/hello.txt`, 'Hello WebDAV');
+```
+
+更详细的有效期说明见 [UCAN有效期与续期机制](./UCAN有效期与续期机制.md)。
+
+#### 创建长期分享链接（warehouse）
+
+```ts
+const share = await storage.client.createShareLink({
+  path: `${storage.appDir}/hello.txt`,
+  // 0 表示不过期（长期分享）
+  expiresValue: 0,
+  expiresUnit: 'day',
+});
+
+console.log('share url =', share.url);
+```
+
+WebDAV 注意：
+- `baseUrl` 只填根地址
+- 子路径通过 `prefix` 指定
+- capability 推荐使用 `with/can`，资源格式统一为 `app:<scope>:<appId>`（常用 `app:all:<appId>`）
+- 在 warehouse 的 UCAN 授权链路中，`createShareLink` / `listShareLinks` 仅允许操作 `app` scope 授权目录内的文件
+- 若走 JWT 或未携带 UCAN `app` scope，请以服务端策略为准，目录隔离不会自动生效
+- 本地调试建议使用 `deriveAppIdFromLocation(window.location)`，会把 `127.0.0.1` / `::1` 统一映射为 `localhost`，避免同端口生成两套应用目录
+
+## 4. 路线二：App 钱包
+
+这条路线的关键不是“是不是手机 App”，而是：
+
+> 能不能把钱包能力适配成前端可调用的 Provider
+
+### 4.1 前提
+
+- 钱包 App 自身提供浏览器内 Provider
+- 或通过桥接层 / SDK 暴露 EIP-1193 接口
+
+如果没有 EIP-1193 或等价适配层，`web3-bs` 不能直接接。
+
+### 4.2 典型流程图
+
+```text
+Connect App Wallet -> Get Provider Adapter -> Request Accounts -> Sign / Login -> Access API
+```
+
+### 4.3 推荐路线
+
+#### 4.3.1 App 钱包只支持标准 EIP-1193
+
+这是最常见情况。
+
+建议走：
+- `getProvider` / 适配后的 `provider`
+- `requestAccounts`
+- `signMessage`
+- `loginWithChallenge`
+- `authFetch`
+- `createWebDavClient`
+
+示例：
+
+```ts
+import {
+  requestAccounts,
+  loginWithChallenge,
+  authFetch,
+} from '@yeying-community/web3-bs';
+
+const provider = appWalletProvider;
+const accounts = await requestAccounts({ provider });
+const address = accounts[0];
+if (!address) throw new Error('No account available');
+
+await loginWithChallenge({
+  provider,
+  address,
+  baseUrl: 'https://api.example.com/api/v1/public/auth',
+});
+
+const res = await authFetch(
+  'https://api.example.com/api/v1/public/profile',
+  { method: 'GET' },
+  { baseUrl: 'https://api.example.com/api/v1/public/auth' }
+);
+```
+
+#### 4.3.2 App 钱包的 UCAN 路径
+
+这种情况可以直接复用“钱包插件路线”的 UCAN 路径。
+
+也就是说：
+- Provider 入口不同
+- `web3-bs` 的 UCAN 调用方式不变（钱包 UCAN RPC 优先，不可用时本地回退）
+
+### 4.4 App 钱包路线的关键限制
+
+- `web3-bs` 不自带 WalletConnect 或 App Bridge 实现
+- 它假设你已经拿到了可调用的 `provider`
+- 如果 App 钱包支持 EIP-1193 签名，UCAN 路线通常可用；是否使用钱包托管 UCAN session 取决于是否实现 UCAN RPC
+
+### 4.5 App 钱包下的 WebDAV
+
+推荐优先走：
+- challenge/SIWE 登录 -> JWT
+- `createWebDavClient` 访问 WebDAV
+
+若 App 钱包可完成签名，就可以走：
+- `initWebDavStorage`
+
+## 5. 路线三：中心化服务
+
+这条路线适合“无钱包插件、无 App 钱包、或业务不强依赖链上身份”的场景。
+
+### 5.1 典型流程图
+
+```text
+Create Session / Login -> Get Token -> Access API -> Access WebDAV
+```
+
+### 5.2 中心化 JWT 路线
+
+如果中心化服务给你的是 JWT，而不是 UCAN，推荐直接用：
+- `setAccessToken`
+- `authFetch`
+- `createWebDavClient`
+
+```ts
+import {
+  setAccessToken,
+  authFetch,
+  createWebDavClient,
+  deriveAppIdFromLocation,
+} from '@yeying-community/web3-bs';
+
+const token = '<ACCESS_TOKEN>';
+setAccessToken(token, { storeToken: true });
+
+const profileRes = await authFetch(
+  'https://api.example.com/api/v1/public/profile',
+  { method: 'GET' }
+);
+
+const appId = deriveAppIdFromLocation(window.location) || 'localhost-8001';
+const webdav = createWebDavClient({
+  baseUrl: 'https://webdav.example.com',
+  prefix: '/dav',
+  token,
+});
+await webdav.upload(`/apps/${appId}/hello.txt`, 'Hello');
+```
+
+### 5.3 中心化 UCAN 路线
+
+如果中心化服务会先发 session，再签发 UCAN，可以用：
+- `createCentralSession`
+- `issueCentralUcan`
+- `authCentralUcanFetch`
+
+```ts
+import {
+  createCentralSession,
+  issueCentralUcan,
+  authCentralUcanFetch,
+} from '@yeying-community/web3-bs';
+
+const session = await createCentralSession({
+  baseUrl: 'https://api.example.com/api/v1/public/auth/central',
+  subject: 'mobile-user-001',
+});
+
+const issued = await issueCentralUcan({
+  baseUrl: 'https://api.example.com/api/v1/public/auth/central',
+  sessionToken: session.sessionToken,
+  audience: 'did:web:api.example.com',
+  capabilities: [{ with: 'app:all:mobile-demo', can: 'read' }],
+});
+
+const res = await authCentralUcanFetch(
+  'https://api.example.com/api/v1/public/profile/me',
+  { method: 'GET' },
+  {
+    ucan: issued.ucan,
+    baseUrl: 'https://api.example.com/api/v1/public/auth/central',
+  }
+);
+```
+
+这条路线下，SDK 负责维护：
+- central session token 缓存
+- UCAN issue 请求封装
+- central UCAN 请求发送
+
+### 5.4 中心化服务路线的边界
+
+- 它不等价于钱包本地 UCAN
+- 它更适合移动端无插件场景
+- 如果你只需要登录后端与访问 WebDAV，JWT 路线通常比中心化 UCAN 更简单
+
+## 6. 三条路线如何选
+
+- 你有浏览器插件钱包：优先“钱包插件路线”
+- 你有钱包 App + Provider 适配层：走“App 钱包路线”
+- 你没有钱包能力，或业务接受中心化身份：走“中心化服务路线”
+
+更细一点：
+- 只要连接、签名、登录：任意 EIP-1193 钱包即可
+- 要走 UCAN 多后端授权：优先钱包 UCAN RPC；不支持时使用 SDK 本地 session 回退
+- 要覆盖移动端无插件：优先中心化服务路线
+
+## 6.5 加密 / 解密（命名安全套件）
+
+DApp 端用独立于钱包密码的"数据密码"对任意数据进行加解密，密文走 `v1:<suite>:...` 格式可粘贴存储。详见 [加解密服务.md](./加解密服务.md)。
+
+```ts
+import { encrypt, decrypt, getSupportedCipherSuites } from '@yeying-community/web3-bs';
+
+const suites = await getSupportedCipherSuites();
+// → ['aes-256-gcm', 'sm4-cbc-hmac-sm3', 'sha-256', 'sm3']
+
+const ciphertext = await encrypt({
+  data: '夜莺钱包敏感数据 🔐',
+  password: 'app-specific-passphrase-2024',
+  suite: 'aes-256-gcm'
+});
+// → v1:aes-256-gcm:<salt>:<iv>:<ciphertext>
+
+const plaintext = new TextDecoder().decode(
+  await decrypt({ ciphertext, password: 'app-specific-passphrase-2024' })
+);
+// → 夜莺钱包敏感数据 🔐
+```
+
+**前提**：站点已 `requestAccounts` 授权 + 钱包已解锁。静默执行，无审批弹窗。
+
+## 7. 最常见的 API 组合
+
+- 插件钱包 + JWT 登录：`getProvider` + `requestAccounts` + `loginWithChallenge` + `authFetch`
+- 插件钱包 + UCAN：`createUcanSession` + `getOrCreateUcanRoot` + `createInvocationUcan`
+- 插件钱包 + 加解密：`getProvider` + `requestAccounts` + `encrypt` / `decrypt`（静默，需先解锁）
+- App 钱包 + JWT 登录：`requestAccounts` + `loginWithChallenge` + `authFetch`
+- 中心化 JWT：`setAccessToken` + `authFetch` + `createWebDavClient`
+- 中心化 UCAN：`createCentralSession` + `issueCentralUcan` + `authCentralUcanFetch`
+
+## 8. 进一步阅读
+
+- [SDK能力](./SDK能力.md)
+- [移动端认证与授权选型指南](./移动端认证与授权选型指南.md)

package/docs//346/226/207/346/241/243/345/257/274/350/210/252.md

@@ -0,0 +1,54 @@
+# 文档导航
+
+这套文档平铺在 `docs/` 目录，按“快速接入 -> 综合能力 -> 有效期机制 -> 移动端补充 -> 评审与契约”组织。
+
+## 文档分工
+
+| 文档 | 主要读者 | 主要回答的问题 | 不重点覆盖 |
+| --- | --- | --- | --- |
+| [快速上手](./快速上手.md) | DApp 前端工程师 | 如何在浏览器里快速接入 SIWE/UCAN/WebDAV | 方案定位与组织边界 |
+| [SDK能力](./SDK能力.md) | 前端负责人、架构师、联调工程师 | 库定位、能力矩阵、账户管理、登录授权与 API 组合 | 逐页面操作指南 |
+| [UCAN有效期与续期机制](./UCAN有效期与续期机制.md) | DApp 前端工程师、后端联调工程师 | UCAN token 有效期配置、skew 判断、过期刷新重试与错误分类 | 后端 UCAN 校验实现 |
+| [加解密服务](./加解密服务.md) | DApp 前端工程师、架构师 | 命名安全套件、encrypt/decrypt/getSupportedCipherSuites 用法、安全模型 | 私钥/助记词保护（那是钱包职责） |
+| [钱包资料授权](./钱包资料授权.md) | DApp 前端工程师、产品安全负责人 | 如何按字段授权并读取钱包用户名和邮箱 | 邮箱真实性验证与业务账号体系 |
+| [移动端认证与授权选型指南](./移动端认证与授权选型指南.md) | 移动端方案设计者 | 无插件场景如何做身份与授权路径选择 | PC 插件细节 |
+| [开放接口规范](./开放接口规范.yaml) | 前后端接口定义维护者 | 标准接口契约 | 业务方案背景 |
+
+## 推荐阅读顺序
+
+1. [快速上手](./快速上手.md)
+2. [SDK能力](./SDK能力.md)
+3. [加解密服务](./加解密服务.md)
+4. [钱包资料授权](./钱包资料授权.md)
+5. [UCAN有效期与续期机制](./UCAN有效期与续期机制.md)
+6. [移动端认证与授权选型指南](./移动端认证与授权选型指南.md)
+7. [开放接口规范](./开放接口规范.yaml)
+
+## 按人群阅读
+
+### DApp 前端工程师
+
+- 首先看 [快速上手](./快速上手.md)
+- 路线与能力看 [SDK能力](./SDK能力.md)
+- 长请求、流式请求和 token 过期处理看 [UCAN有效期与续期机制](./UCAN有效期与续期机制.md)
+- 移动端补充看 [移动端认证与授权选型指南](./移动端认证与授权选型指南.md)
+- 加密/解密 DApp 敏感数据看 [加解密服务](./加解密服务.md)
+
+### 钱包 / 后端联调工程师
+
+- 协议流程、边界与 API 细节看 [SDK能力](./SDK能力.md)
+- token 有效期、错误分类和续期策略看 [UCAN有效期与续期机制](./UCAN有效期与续期机制.md)
+- 接口契约看 [开放接口规范](./开放接口规范.yaml)
+
+### 架构与方案设计者
+
+- 能力边界与路线取舍先看 [SDK能力](./SDK能力.md)
+- 授权有效期与长请求体验风险看 [UCAN有效期与续期机制](./UCAN有效期与续期机制.md)
+- 移动端特殊路径看 [移动端认证与授权选型指南](./移动端认证与授权选型指南.md)
+- 接口标准看 [开放接口规范](./开放接口规范.yaml)
+
+## 维护原则
+
+- `docs/` 目录保持平铺，不再分层级子目录。
+- 一个文档聚焦一个核心问题，交叉引用而不是重复展开。
+- 文档名与标题保持一致，避免“文件名是 A、内容其实是 B”。

package/docs//347/247/273/345/212/250/347/253/257/350/256/244/350/257/201/344/270/216/346/216/210/346/235/203/351/200/211/345/236/213/346/214/207/345/215/227.md

@@ -0,0 +1,151 @@
+# 移动端认证与授权选型指南
+
+本文档用于在“移动端没有浏览器钱包插件”的前提下，统一评估认证与授权路径。
+目标是让你先做路线决策，再落到 `web3-bs` 的 API 组合。
+
+## 1. 快速对比
+
+| 路径 | 身份来源 | UCAN 形态 | 接入复杂度 | 推荐场景 |
+| --- | --- | --- | --- | --- |
+| 钱包 App 连接（WalletConnect / Deep Link） | 链上钱包 | 可支持（依赖钱包能力） | 中 | 需要尽量保留钱包体验与链上身份 |
+| 嵌入式钱包（托管 / MPC） | 钱包 SDK | 可支持（依赖 SDK） | 中-高 | 移动端无插件且可接受钱包 SDK 成本 |
+| SSO / WebAuthn（JWT） | 中心化身份 | 不使用 UCAN | 中 | 登录体验优先、业务不强依赖链上身份 |
+| 中心化 UCAN 发行 | 中心化身份 + Issuer 服务 | 支持（中心化信任） | 高 | 需要 UCAN 令牌形态并接受中心化信任 |
+| PC 首次绑定 + 移动端长期会话 | PC 钱包 + 后端长期会话 | 通常移动端侧不直接用钱包 UCAN | 中-高 | 允许 PC 首次认证，移动端长期免钱包 |
+| 传统账号（手机号/邮箱+2FA） | 中心化账号 | 不使用 UCAN | 低 | 最快上线、实现成本最低 |
+
+## 2. 决策顺序
+
+1. 是否必须保留链上身份来源？
+2. 是否可接受用户安装钱包 App 或接入钱包 SDK？
+3. 是否接受中心化身份体系（SSO / WebAuthn / 账号密码）？
+4. 是否必须保留 UCAN 令牌形态？
+5. 是否允许“PC 首次绑定、移动端长期会话”作为折中方案？
+
+## 3. 路径详解
+
+### 3.1 钱包 App 连接（WalletConnect / Deep Link）
+
+适用：
+- 用户愿意安装钱包 App
+- 业务希望保留链上身份
+- 希望移动端体验接近 PC 钱包插件
+
+核心前提：
+- 移动端可拿到 EIP-1193 provider
+- 若要完整 UCAN 流程，钱包需支持 `yeying_ucan_session` / `yeying_ucan_sign`
+
+`web3-bs` 推荐组合：
+- 登录：`requestAccounts` + `loginWithChallenge` + `authFetch`
+- UCAN：`createUcanSession` + `getOrCreateUcanRoot` + `createInvocationUcan`
+- WebDAV：`initWebDavStorage` 或 `createWebDavClient`
+
+### 3.2 嵌入式钱包（托管 / MPC）
+
+适用：
+- 不希望用户额外安装插件
+- 可以接受钱包 SDK、合规和运维成本
+
+核心前提：
+- 嵌入式钱包 SDK 可暴露 EIP-1193 provider
+- 若仅支持 `personal_sign`，则只适合 SIWE/JWT 路线
+
+`web3-bs` 推荐组合：
+- 登录：`requestAccounts` + `loginWithChallenge` + `authFetch`
+- UCAN（可选）：同 3.1（前提是 SDK 支持钱包 UCAN RPC 或使用本地回退）
+- WebDAV：`createWebDavClient` / `initWebDavStorage`
+
+### 3.3 SSO / WebAuthn（JWT）
+
+适用：
+- 登录成功率和移动端体验优先
+- 不强依赖链上身份语义
+
+核心思路：
+- 认证后端完成 SSO 或 Passkey 验证并签发 JWT
+- DApp 使用 JWT 调用多后端
+
+`web3-bs` 推荐组合：
+- `setAccessToken` + `authFetch` + `refreshAccessToken`
+- WebDAV 使用 `createWebDavClient`（Bearer JWT）
+
+备注：
+- 该路径不依赖钱包，不使用钱包 UCAN。
+
+### 3.4 中心化 UCAN 发行
+
+适用：
+- 希望保持 UCAN 令牌形态
+- 接受中心化 Issuer 信任模型
+
+核心思路：
+- 用户先走中心化登录（SSO/WebAuthn/JWT）
+- Issuer 服务签发 UCAN（`iss` 为 Issuer DID）
+- 业务后端信任 Issuer 公钥并校验 `aud` / `cap` / `exp`
+
+`web3-bs` 推荐组合：
+- `getCentralIssuerInfo`
+- `createCentralSession`
+- `issueCentralUcan` / `createAndIssueCentralUcan`
+- `authCentralUcanFetch`
+
+边界说明：
+- 这是“中心化 UCAN”，不是“用户钱包控制 UCAN”。
+
+### 3.5 PC 首次绑定 + 移动端长期会话
+
+适用：
+- 用户可在 PC 端完成一次钱包认证
+- 移动端希望后续免钱包、低摩擦访问
+
+核心思路：
+- PC 钱包登录后，后端签发一次性绑定票据
+- 移动端绑定设备并换取长期 JWT/会话
+
+`web3-bs` 推荐组合：
+- PC 端：标准钱包登录或 UCAN 流程
+- 移动端：`setAccessToken` + `authFetch` + `createWebDavClient`
+
+### 3.6 传统账号（手机号/邮箱 + 2FA）
+
+适用：
+- 业务不依赖链上身份
+- 优先追求实现效率和稳定性
+
+核心思路：
+- 账号体系签发 JWT
+- 多后端统一校验 JWT
+
+`web3-bs` 推荐组合：
+- `setAccessToken` + `authFetch` + `refreshAccessToken`
+- WebDAV：`createWebDavClient`
+
+## 4. 实施建议
+
+### 4.1 先定“身份来源”，再定“令牌形态”
+
+- 身份来源：钱包 / SSO / 账号体系
+- 令牌形态：JWT / 钱包 UCAN / 中心化 UCAN
+
+这两个维度分开设计，文档和实现会更清晰。
+
+### 4.2 优先使用统一资源模型
+
+无论 JWT 还是 UCAN，资源权限建议统一到服务端策略，例如：
+- `app:all:<appId>`
+- `app:read:<appId>`
+- `app:write:<appId>`
+
+这样可减少多后端权限映射成本。
+
+### 4.3 明确中心化 UCAN 的信任边界
+
+- 钱包 UCAN：用户控制签名能力
+- 中心化 UCAN：Issuer 服务控制签发能力
+
+这两者在安全语义上不同，文档与产品上应明确标注。
+
+## 5. 推荐阅读
+
+- [快速上手](./快速上手.md)
+- [SDK能力](./SDK能力.md)