@yeying-community/web3-bs 1.0.16 → 1.0.17

package/docs//351/222/261/345/214/205/350/265/204/346/226/231/346/216/210/346/235/203.md

@@ -0,0 +1,154 @@
+# 钱包资料授权
+
+钱包资料授权让 Web3 应用在用户明确同意后读取钱包中的公开用户名或邮箱。它基于 EIP-1193 Provider 和钱包权限 RPC，不会把资料隐式附加到 `eth_accounts`、SIWE 消息或 UCAN Token 中。
+
+## 支持字段
+
+| 字段 | 作用域 | 说明 |
+| --- | --- | --- |
+| `username` | 当前钱包账户 | 用户为当前账户设置的公开用户名 |
+| `email` | 钱包资料 | 用户主动填写的邮箱，当前不代表已经验证 |
+
+SDK 不支持任意字段名。手机号、密码、助记词和私钥等字段会在调用钱包前直接被拒绝。
+
+## 推荐接入
+
+```ts
+import { getProvider, connectAndGetWalletProfile } from '@yeying-community/web3-bs';
+
+const provider = await getProvider({ preferYeYing: true });
+if (!provider) throw new Error('未检测到钱包');
+
+const result = await connectAndGetWalletProfile({
+  provider,
+  fields: ['username', 'email'],
+});
+
+console.log(result.address);
+console.log(result.chainId);
+console.log(result.profile.username);
+console.log(result.profile.email);
+```
+
+首次调用依次执行：连接账户、查询已有权限、只申请缺少的字段、显示钱包审批、读取已授权资料。后续调用会复用已有权限。
+
+## 分步调用
+
+### 查询权限
+
+```ts
+import { getWalletProfilePermission, getGrantedProfileFields } from '@yeying-community/web3-bs';
+
+const permission = await getWalletProfilePermission(provider);
+const fields = getGrantedProfileFields(permission);
+```
+
+没有资料权限时返回 `null`。
+
+### 请求权限
+
+```ts
+await requestWalletProfilePermission({ provider, fields: ['username'] });
+```
+
+资料权限必须在站点已连接钱包后申请。邮箱更敏感，只应在业务确实需要时申请。
+
+### 读取资料
+
+```ts
+const result = await getWalletProfile({ provider, fields: ['username'] });
+```
+
+返回类型：
+
+```ts
+type WalletProfileResult = {
+  address: string;
+  chainId: string | null;
+  profile: { username?: string; email?: string };
+};
+```
+
+只返回本次明确请求且已经授权的字段。尚未填写的字段可以是空字符串。
+
+### 撤销权限
+
+```ts
+await revokeWalletProfilePermission(provider);
+```
+
+这会撤销当前站点全部 `yeying_profile` 字段权限，但不会断开账户连接。
+
+## 静默读取模式
+
+页面初始化时不希望自动弹出资料审批，可以禁用自动申请：
+
+```ts
+const result = await connectAndGetWalletProfile({
+  provider,
+  fields: ['username'],
+  requestPermission: false,
+});
+```
+
+权限不存在时钱包会返回未授权错误。
+
+## 错误处理
+
+```ts
+try {
+  await connectAndGetWalletProfile({ provider, fields: ['username', 'email'] });
+} catch (error) {
+  const info = classifyWalletError(error);
+  if (info.type === 'userRejected') {
+    // 不要立即重复弹窗。
+  } else if (info.type === 'disconnected') {
+    // 提示用户解锁或重新连接钱包。
+  }
+}
+```
+
+| Provider code | 含义 |
+| --- | --- |
+| `4001` | 用户拒绝连接或资料共享 |
+| `4100` | 站点未连接、字段未授权或授权账户不是当前账户 |
+| `-32602` | 字段为空或包含不支持字段 |
+| `-32601` | 当前钱包不支持资料能力 |
+
+## 与 SIWE 和 UCAN 的关系
+
+- `eth_requestAccounts` 建立站点与账户连接。
+- SIWE 证明用户控制钱包地址，通常用于后端登录。
+- UCAN 授权主体执行资源操作。
+- 钱包资料授权负责在用户同意后读取显示资料。
+
+用户名和邮箱不是身份真实性证明，不能替代 SIWE 验签。当前邮箱没有验证声明；需要可信邮箱时，应由应用后端完成验证码或邮件链接验证。
+
+## 隐私与安全
+
+- 默认只申请 `username`，确有需要再申请 `email`。
+- 不要在页面加载时无条件触发资料审批。
+- 不要把资料写入 URL、公开日志、链上交易或公开 UCAN capability。
+- 服务端应把资料绑定到返回的 `address`。
+- 账户变化后重新读取资料，不要沿用旧账户资料。
+- SDK 不缓存资料，应用自行决定缓存周期和清理策略。
+
+## 原始 RPC
+
+```js
+await ethereum.request({ method: 'eth_requestAccounts' });
+await ethereum.request({
+  method: 'wallet_requestPermissions',
+  params: [{ yeying_profile: { fields: ['username', 'email'] } }],
+});
+const result = await ethereum.request({
+  method: 'yeying_getProfile',
+  params: [{ fields: ['username', 'email'] }],
+});
+```
+
+SDK 在此基础上提供字段类型约束、已有权限复用、缺失字段增量申请和返回值校验。
+
+## 兼容性
+
+资料能力是 YeYing 钱包扩展能力。其他 EIP-1193 钱包可能返回 `-32601 Method not found`。应用应把资料视为可选增强能力，不能因为钱包不支持该接口而阻止标准钱包登录。

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "@yeying-community/web3-bs",
-  "version": "1.0.16",
+  "version": "1.0.17",
   "author": "yeying.community@gmail.com",
   "description": "Browser-side DApp access SDK for EIP-1193, SIWE, UCAN, central UCAN and WebDAV",
   "module": "dist/web3-bs.esm.js",
   "browser": "dist/web3-bs.umd.js",
   "types": "dist/index.d.ts",
   "files": [
-    "dist/**/*"
+    "dist/**/*",
+    "docs/**/*"
   ],
   "scripts": {
     "dev": "rollup -c -w",