@yeying-community/web3-bs 1.0.2 → 1.0.4

package/README.md

@@ -3,143 +3,19 @@
 轻量级注入钱包 SDK，专注浏览器端 EIP-1193 Provider。默认优先选择 YeYing Wallet（支持 EIP-6963 多钱包发现）。
 仅支持浏览器环境（依赖 `window` / `localStorage` / `fetch`）。
 
+功能要点：
+- 浏览器端 EIP-1193 Provider 辅助库
+- 默认优先 YeYing Wallet
+- 内置 `signMessage` / `loginWithChallenge` / `refresh` / `logout` 等方法
+- 支持 UCAN Session + SIWE Bridge，用于多后端授权
+
 ## 安装
 
 ```bash
 npm install @yeying-community/web3-bs
 ```
 
-## 钱包交互 API
-
-### Provider 发现
-- `getProvider(options?)`
-  - 自动监听 `eip6963:announceProvider`
-  - 默认优先 YeYing（`isYeYing` 或 `rdns: io.github.yeying`）
-
-### 核心方法
-- `requestAccounts({ provider? })`
-- `getAccounts(provider?)`
-- `getChainId(provider?)`
-- `getBalance(provider?, address?, blockTag?)`
-- `signMessage({ provider?, message, address?, method? })`
-  - `method` 默认 `personal_sign`
-
-### 事件
-- `onAccountsChanged(provider, handler)`
-- `onChainChanged(provider, handler)`
-
-## 后端交互 API（推荐标准）
-OpenAPI 规范：`docs/openapi.yaml`
-
-### 响应封装（严格）
-所有响应必须使用以下封装结构：
-
-```json
-{
-  "code": 0,
-  "message": "ok",
-  "data": { "...": "..." },
-  "timestamp": 1730000000000
-}
-```
-
-- `code = 0` 表示成功
-- `code != 0` 表示失败；`data` 应为 `null`
-
-### 1) 获取 Challenge
-
-`POST /api/v1/public/auth/challenge`
-
-请求
-```json
-{ "address": "0xabc123..." }
-```
-
-响应
-```json
-{
-  "code": 0,
-  "message": "ok",
-  "data": {
-    "address": "0xabc123...",
-    "challenge": "Sign to login...",
-    "nonce": "random",
-    "issuedAt": 1730000000000,
-    "expiresAt": 1730000300000
-  },
-  "timestamp": 1730000000000
-}
-```
-
-### 2) 验证签名
-
-`POST /api/v1/public/auth/verify`
-
-请求
-```json
-{ "address": "0xabc123...", "signature": "0x..." }
-```
-
-响应
-```json
-{
-  "code": 0,
-  "message": "ok",
-  "data": {
-    "address": "0xabc123...",
-    "token": "access-token",
-    "expiresAt": 1730086400000,
-    "refreshExpiresAt": 1730686400000
-  },
-  "timestamp": 1730000000000
-}
-```
-
-说明
-- `verify` 应设置 httpOnly 的 `refresh_token` Cookie（用于刷新 access token）。
-- 访问受保护接口时，前端使用 `Authorization: Bearer <access-token>`。
-
-### 3) 刷新 Access Token
-
-`POST /api/v1/public/auth/refresh`
-
-请求
-- 依赖 httpOnly `refresh_token` Cookie
-
-响应
-```json
-{
-  "code": 0,
-  "message": "ok",
-  "data": {
-    "address": "0xabc123...",
-    "token": "new-access-token",
-    "expiresAt": 1730086400000,
-    "refreshExpiresAt": 1730686400000
-  },
-  "timestamp": 1730000000000
-}
-```
-
-### 4) 退出登录
-
-`POST /api/v1/public/auth/logout`
-
-响应
-```json
-{
-  "code": 0,
-  "message": "ok",
-  "data": { "logout": true },
-  "timestamp": 1730000000000
-}
-```
-
-### SDK 绑定
-- `loginWithChallenge` 会从 `data.challenge` 读取 challenge，从 `data.token` 读取 token。
-- `refreshAccessToken` 调用 `/refresh` 并更新 access token（默认 `credentials: 'include'`）。
-- `authFetch` 会自动携带 access token，遇到 401 会尝试刷新再重试一次。
-- `logout` 会清理刷新 Cookie 并清空本地 access token（若设置 `storeToken`）。
+更多集成与流程说明见 `docs/sdk-design.md`。
 
 ## 示例
 
@@ -150,92 +26,49 @@ OpenAPI 规范：`docs/openapi.yaml`
 - Backend server (Python): `examples/backend/python/app.py`
 - Backend server (Java): `examples/backend/java/src/main/java/com/yeying/demo/AuthServer.java`
 
-## UCAN 授权（SIWE Bridge）
-
-SDK 通过 YeYing 钱包生成 UCAN Session Key 并完成签名（由钱包后台隔离私钥）。
-Root UCAN 基于 SIWE 签名，
-用于多后端统一鉴权。UCAN 以 `Authorization: Bearer <UCAN>` 发送，后端会验证 UCAN 证明链与能力。
+## 本地验证
 
-新增 API：
-- `createUcanSession(options?)`
-- `createRootUcan(options)`
-- `createDelegationUcan(options)`
-- `createInvocationUcan(options)`
-- `authUcanFetch(url, init?, options?)`
+1. 构建 SDK：`npm run build`
+2. 启动后端：`scripts/backend.sh start node`（将 `node` 替换为 `go` / `python` / `java`）
+3. 启动前端：`python3 -m http.server 8001 --bind 127.0.0.1`
+4. 访问：`http://127.0.0.1:8001/examples/frontend/dapp.html`
+5. 确保安装 YeYing 钱包扩展插件
+6. 点击：`Detect Provider` → `Connect Wallet` → `Login`
 
-示例：
-```ts
-const session = await createUcanSession();
-const root = await createRootUcan({
-  provider,
-  session,
-  capabilities: [{ resource: 'profile', action: 'read' }],
-});
-
-const ucan = await createInvocationUcan({
-  issuer: session,
-  audience: 'did:web:localhost:3203',
-  capabilities: [{ resource: 'profile', action: 'read' }],
-  proofs: [root],
-});
-
-const res = await authUcanFetch('http://localhost:3203/api/v1/private/profile', { method: 'GET' }, { ucan });
-console.log(await res.json());
-```
+提示：如果前端来自其他域名，请设置
+`COOKIE_SAMESITE=none` 且 `COOKIE_SECURE=true` 并使用 HTTPS，
+以便 `refresh_token` Cookie 能随 `credentials: 'include'` 发送。
 
-后端默认要求的能力为 `resource=profile`、`action=read`，可通过环境变量覆盖：
-- `UCAN_AUD`：服务 DID（默认 `did:web:localhost:3203`）
-- `UCAN_RESOURCE`：资源（默认 `profile`）
-- `UCAN_ACTION`：动作（默认 `read`）
+## 后端脚本用法
 
-提示：如需可转授权，使用 `createDelegationUcan` 创建委任链，再用被委任的 Key 生成 Invocation UCAN。
+通用格式：
+`./scripts/backend.sh <start|stop|restart|status> <node|go|python|java|all> [--setup] [--no-stop]`
 
-## WebDAV 存储（Storage）
+示例：
+```bash
+# 启动 Node 后端
+./scripts/backend.sh start node
 
-提供基于 WebDAV 服务的文件操作封装（上传/下载/删除/目录等），适配 `webdav` 项目 API。
+# 启动 Go 后端并安装依赖/构建
+./scripts/backend.sh start go --setup
 
-示例：
-```ts
-import { createWebDavClient, loginWithChallenge } from '@yeying-community/web3-bs';
-
-const login = await loginWithChallenge({
-  provider,
-  baseUrl: 'http://localhost:6065/api/v1/public/auth',
-  storeToken: false,
-});
-
-const client = createWebDavClient({
-  baseUrl: 'http://localhost:6065',
-  token: login.token,
-  prefix: '/',
-});
-
-const listingXml = await client.listDirectory('/');
-await client.upload('/docs/hello.txt', 'Hello WebDAV');
-const content = await client.downloadText('/docs/hello.txt');
-```
+# 查看全部后端状态
+./scripts/backend.sh status all
 
-常用方法：
-- `listDirectory(path?, depth?)`（PROPFIND，返回 XML 文本）
-- `upload(path, content, contentType?)`
-- `download(path)` / `downloadText(path)` / `downloadArrayBuffer(path)`
-- `createDirectory(path)`（MKCOL）
-- `remove(path)`（DELETE）
-- `move(path, destination, overwrite?)`
-- `copy(path, destination, overwrite?)`
-- `getQuota()` / `listRecycle()` / `recoverRecycle(hash)` / `deleteRecycle(hash)` / `clearRecycle()`
+# 重启 Python 后端
+./scripts/backend.sh restart python
 
-## 本地验证
+# 停止所有后端
+./scripts/backend.sh stop all
 
-1. 构建 SDK：`npm run build`
-2. 启动后端：`node examples/backend/node/server.js`
-3. 启动前端：`python3 -m http.server 8001`，然后在浏览器输入访问地址：`http://localhost:8001/examples/frontend/dapp.html`
-4. 确保安装 YeYing 钱包扩展插件
-5. 点击：`Detect Provider` → `Connect Wallet` → `Login`
+# 同时启动多个后端（不停止已运行的服务）
+./scripts/backend.sh start all --no-stop
+```
 
-提示：如果前端来自其他域名，请设置
-`COOKIE_SAMESITE=none` 且 `COOKIE_SECURE=true` 并使用 HTTPS，
-以便 `refresh_token` Cookie 能随 `credentials: 'include'` 发送。
+说明：
+- 日志位于 `.tmp/backend-logs`
+- 进程 PID 位于 `.tmp/backend-pids`
+- 可通过环境变量传递端口/秘钥/TTL 等配置（如 `PORT`、`JWT_SECRET` 等）
 
 ## 多后端联调（不同端口）
 
@@ -253,8 +86,8 @@ const content = await client.downloadText('/docs/hello.txt');
 - Python `3204`
 
 前端调用不同端口的后端时：
-- 将前端 Origin 加入 `CORS_ORIGINS`（例如 `http://localhost:3203`）
-- UCAN 调用的 `audience` 与后端 `UCAN_AUD` 一致（如 `did:web:localhost:3202`）
+- 将前端 Origin 加入 `CORS_ORIGINS`（例如 `http://127.0.0.1:3203`）
+- UCAN 调用的 `audience` 与后端 `UCAN_AUD` 一致（如 `did:web:127.0.0.1:3202`）
 
 提示：`examples/frontend/dapp.html` 已内置多后端列表，可在一次 UCAN 授权后依次调用多个服务。
 
@@ -262,4 +95,27 @@ const content = await client.downloadText('/docs/hello.txt');
 
 ### 刷新token失败
 
-清理旧 Cookie 后重新登录：在浏览器 DevTools → Application → Cookies → http://localhost:8001 删除 refresh_token，再点 Login 后再点 Refresh Token。
+清理旧 Cookie 后重新登录：在浏览器 DevTools → Application → Cookies → http://127.0.0.1:8001 删除 refresh_token，再点 Login 后再点 Refresh Token。
+
+### WebDAV 提示 invalid token
+
+报错示例：`authentication failed` / `invalid token`（通常来自 WebDAV 服务端鉴权中间件）。
+
+排查与解决：
+- 确认 `baseUrl` 指向 WebDAV 服务（默认 `http://127.0.0.1:6065`），不要误用 320x 认证后端。
+- `audience` 必须与 WebDAV 服务端 `UCAN_AUD` 一致（例如 `did:web:127.0.0.1:6065`）。
+- `capabilities` 与服务端要求一致（`UCAN_RESOURCE` / `UCAN_ACTION`）。
+- Token 过期或缓存异常时，清理 UCAN 会话并重新登录/生成 Root + Invocation。
+
+### UCAN audience mismatch
+
+日志示例：
+```
+[2026-01-31T05:19:44.478Z] UCAN profile failed { error: 'UCAN audience mismatch' }
+```
+
+解决思路：
+- 生成 UCAN 时的 `audience` 必须与目标后端的 `UCAN_AUD` 完全一致。
+  - 例如 Node 后端：`did:web:127.0.0.1:3203`
+  - 例如 WebDAV 服务：`did:web:127.0.0.1:6065`
+- 多后端联调时，确保每个后端使用对应的 `audience` 生成 Invocation UCAN。

package/dist/auth/provider.d.ts

@@ -1,10 +1,12 @@
-import { Eip1193Provider, ProviderDiscoveryOptions, ProviderInfo, RequestAccountsOptions } from './types';
+import { Eip1193Provider, ProviderDiscoveryOptions, ProviderInfo, RequestAccountsOptions, AccountSelection, PreferredAccountOptions, WatchAccountsOptions, AccountsChangedHandler } from './types';
 export declare function isYeYingProvider(provider?: Eip1193Provider | null, info?: ProviderInfo): boolean;
 export declare function getProvider(options?: ProviderDiscoveryOptions): Promise<Eip1193Provider | null>;
 export declare function requireProvider(options?: ProviderDiscoveryOptions): Promise<Eip1193Provider>;
 export declare function requestAccounts(options?: RequestAccountsOptions): Promise<string[]>;
 export declare function getAccounts(provider?: Eip1193Provider): Promise<string[]>;
 export declare function getChainId(provider?: Eip1193Provider): Promise<string | null>;
+export declare function getPreferredAccount(options?: PreferredAccountOptions): Promise<AccountSelection>;
+export declare function watchAccounts(provider: Eip1193Provider, handler: AccountsChangedHandler, options?: WatchAccountsOptions): () => void;
 export declare function getBalance(provider?: Eip1193Provider, address?: string, blockTag?: string): Promise<string>;
 export declare function onAccountsChanged(provider: Eip1193Provider, handler: (accounts: string[]) => void): () => void;
 export declare function onChainChanged(provider: Eip1193Provider, handler: (chainId: string) => void): () => void;

package/dist/auth/types.d.ts

@@ -34,6 +34,20 @@ export interface ProviderDiscoveryOptions {
 export interface RequestAccountsOptions {
     provider?: Eip1193Provider;
 }
+export type AccountSelection = {
+    account: string | null;
+    accounts: string[];
+};
+export interface PreferredAccountOptions extends RequestAccountsOptions {
+    storageKey?: string;
+    autoConnect?: boolean;
+    preferStored?: boolean;
+}
+export interface WatchAccountsOptions {
+    storageKey?: string;
+    preferStored?: boolean;
+}
+export type AccountsChangedHandler = (payload: AccountSelection) => void;
 export interface SignMessageOptions {
     provider?: Eip1193Provider;
     message: string;

package/dist/auth/ucan.d.ts

@@ -86,6 +86,7 @@ export declare function createUcanSession(options?: CreateUcanSessionOptions): P
 export declare function clearUcanSession(id?: string): Promise<void>;
 export declare function storeUcanRoot(root: UcanRootProof, id?: string): Promise<void>;
 export declare function getStoredUcanRoot(id?: string): Promise<UcanRootProof | null>;
+export declare function getOrCreateUcanRoot(options: CreateRootUcanOptions): Promise<UcanRootProof>;
 export declare function createRootUcan(options: CreateRootUcanOptions): Promise<UcanRootProof>;
 export declare function createDelegationUcan(options: CreateUcanTokenOptions): Promise<string>;
 export declare function createInvocationUcan(options: CreateUcanTokenOptions): Promise<string>;

package/dist/dapp.d.ts

@@ -0,0 +1,48 @@
+import { loginWithChallenge } from './auth/siwe';
+import { UcanCapability, UcanRootProof, UcanSessionKey } from './auth/ucan';
+import { Eip1193Provider, LoginWithChallengeOptions } from './auth/types';
+import { WebDavClient } from './storage/webdav';
+export type InitWebDavStorageOptions = {
+    baseUrl: string;
+    audience: string;
+    prefix?: string;
+    appDir?: string;
+    appId?: string;
+    ensureAppDir?: boolean;
+    capabilities?: UcanCapability[];
+    invocationCapabilities?: UcanCapability[];
+    provider?: Eip1193Provider;
+    sessionId?: string;
+    session?: UcanSessionKey;
+    root?: UcanRootProof;
+    rootExpiresInMs?: number;
+    invocationExpiresInMs?: number;
+    notBeforeMs?: number;
+    fetcher?: typeof fetch;
+    credentials?: RequestCredentials;
+};
+export type InitWebDavStorageResult = {
+    client: WebDavClient;
+    token: string;
+    appDir?: string;
+    session: UcanSessionKey;
+    root: UcanRootProof;
+};
+export type InitDappSessionOptions = {
+    provider?: Eip1193Provider;
+    address?: string;
+    appAuth?: LoginWithChallengeOptions;
+    webdav?: InitWebDavStorageOptions;
+};
+export type InitDappSessionResult = {
+    provider: Eip1193Provider;
+    address?: string;
+    appLogin?: Awaited<ReturnType<typeof loginWithChallenge>>;
+    ucanSession?: UcanSessionKey;
+    ucanRoot?: UcanRootProof;
+    webdavClient?: WebDavClient;
+    webdavToken?: string;
+    webdavAppDir?: string;
+};
+export declare function initWebDavStorage(options: InitWebDavStorageOptions): Promise<InitWebDavStorageResult>;
+export declare function initDappSession(options: InitDappSessionOptions): Promise<InitDappSessionResult>;

package/dist/index.d.ts

@@ -1,2 +1,3 @@
 export * from './auth';
 export * from './storage';
+export * from './dapp';

package/dist/storage/webdav.d.ts

@@ -42,6 +42,7 @@ export declare class WebDavClient {
     downloadArrayBuffer(path: string): Promise<ArrayBuffer>;
     upload(path: string, content: BodyInit, contentType?: string): Promise<Response>;
     createDirectory(path: string): Promise<Response>;
+    ensureDirectory(path: string): Promise<void>;
     remove(path: string): Promise<Response>;
     move(path: string, destination: string, overwrite?: boolean): Promise<Response>;
     copy(path: string, destination: string, overwrite?: boolean): Promise<Response>;