@yeying-community/web3-bs 1.0.5 → 1.0.7

package/README.md

@@ -1,13 +1,14 @@
-# YeYing Inject Wallet SDK
+# YeYing Browser DApp Access SDK
 
-轻量级注入钱包 SDK，专注浏览器端 EIP-1193 Provider。默认优先选择 YeYing Wallet（支持 EIP-6963 多钱包发现）。
-仅支持浏览器环境（依赖 `window` / `localStorage` / `fetch`）。
+`web3-bs` 是浏览器端 DApp 接入 SDK，用于统一封装：
+
+- 钱包连接（EIP-1193 / EIP-6963）
+- SIWE challenge 登录与 JWT 鉴权请求
+- UCAN 多后端授权（钱包 UCAN RPC 优先，失败可回退本地 Ed25519 session）
+- 中心化 UCAN 发行服务接入
+- WebDAV 文件访问与应用目录初始化
 
-功能要点：
-- 浏览器端 EIP-1193 Provider 辅助库
-- 默认优先 YeYing Wallet
-- 内置 `signMessage` / `loginWithChallenge` / `refresh` / `logout` 等方法
-- 支持 UCAN Session + SIWE Bridge，用于多后端授权
+仅支持浏览器环境（依赖 `window` / `localStorage` / `fetch`）。
 
 ## 安装
 
@@ -15,68 +16,112 @@
 npm install @yeying-community/web3-bs
 ```
 
-更多集成与流程说明见 `docs/sdk-design.md`。
+## 能力概览
 
-## 示例
+### 1) Provider 与账户
 
-- Frontend Dapp (HTML): `examples/frontend/dapp.html`
-- Frontend Dapp (TS module): `examples/frontend/main.ts`
-- Backend server (Node): `examples/backend/node/server.js`
-- Backend server (Go): `examples/backend/go/main.go`
-- Backend server (Python): `examples/backend/python/app.py`
-- Backend server (Java): `examples/backend/java/src/main/java/com/yeying/demo/AuthServer.java`
+- `getProvider` / `requireProvider`
+- `requestAccounts` / `getAccounts` / `getPreferredAccount` / `watchAccounts`
+- `getChainId` / `getBalance`
+- `onAccountsChanged` / `onChainChanged`
 
-## 本地验证
+### 2) SIWE + JWT
 
-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`
+- `signMessage`
+- `loginWithChallenge`
+- `authFetch`
+- `refreshAccessToken`
+- `logout`
+- `getAccessToken` / `setAccessToken` / `clearAccessToken`
 
-提示：如果前端来自其他域名，请设置
-`COOKIE_SAMESITE=none` 且 `COOKIE_SECURE=true` 并使用 HTTPS，
-以便 `refresh_token` Cookie 能随 `credentials: 'include'` 发送。
+### 3) UCAN（钱包优先 + 本地回退）
 
-## 后端脚本用法
+- `createUcanSession` / `getUcanSession`
+- `getOrCreateUcanRoot` / `createRootUcan`
+- `createDelegationUcan` / `createInvocationUcan`
+- `authUcanFetch`
+- `normalizeUcanCapabilities`
 
-通用格式：
-`./scripts/backend.sh <start|stop|restart|status> <node|go|python|java|all> [--setup] [--no-stop]`
+说明：
+- 能调用 `yeying_ucan_session` / `yeying_ucan_sign` 时，优先用钱包侧 UCAN session 签名。
+- 不支持上述钱包 RPC 时，SDK 会回退到浏览器本地 Ed25519 session（IndexedDB 持久化）。
 
-示例：
-```bash
-# 启动 Node 后端
-./scripts/backend.sh start node
+### 4) 中心化 UCAN
+
+- `getCentralIssuerInfo`
+- `createCentralSession`
+- `issueCentralUcan`
+- `createAndIssueCentralUcan`
+- `authCentralUcanFetch`
+- `getCentralSessionToken` / `setCentralSessionToken` / `clearCentralSessionToken`
 
-# 启动 Go 后端并安装依赖/构建
-./scripts/backend.sh start go --setup
+### 5) WebDAV 与 DApp 会话编排
 
-# 查看全部后端状态
-./scripts/backend.sh status all
+- `createWebDavClient`
+- `initWebDavStorage`（自动生成/复用 WebDAV Invocation UCAN，可自动创建应用目录）
+- `initDappSession`（SIWE 登录 + WebDAV UCAN 初始化）
+- `deriveAppIdFromLocation` / `deriveAppIdFromHost`
 
-# 重启 Python 后端
-./scripts/backend.sh restart python
+## 常见接入方式
 
-# 停止所有后端
-./scripts/backend.sh stop all
+### 单后端登录（SIWE + JWT）
 
-# 同时启动多个后端（不停止已运行的服务）
-./scripts/backend.sh start all --no-stop
+```ts
+import { loginWithChallenge, authFetch } from '@yeying-community/web3-bs';
+
+await loginWithChallenge({
+  baseUrl: 'http://localhost:3203/api/v1/public/auth',
+  storeToken: false,
+});
+
+const res = await authFetch(
+  'http://localhost:3203/api/v1/public/profile',
+  { method: 'GET' },
+  { baseUrl: 'http://localhost:3203/api/v1/public/auth', storeToken: false }
+);
 ```
 
-说明：
-- 日志位于 `.tmp/backend-logs`
-- 进程 PID 位于 `.tmp/backend-pids`
-- 可通过环境变量传递端口/秘钥/TTL 等配置（如 `PORT`、`JWT_SECRET` 等）
+### 多后端 UCAN + WebDAV
+
+```ts
+import { initWebDavStorage, deriveAppIdFromLocation } from '@yeying-community/web3-bs';
+
+const appId = deriveAppIdFromLocation(window.location) || 'localhost-8001';
+const webdav = await initWebDavStorage({
+  baseUrl: 'http://localhost:6065',
+  audience: 'did:web:localhost:6065',
+  appId,
+  capabilities: [{ with: `app:all:${appId}`, can: 'write' }],
+});
+
+await webdav.client.upload(`${webdav.appDir}/hello.txt`, 'Hello WebDAV');
+```
 
-## 多后端联调（不同端口）
+## Demo
 
-可同时启动多语言后端（不同端口），验证 UCAN 多后端授权：
+- 前端 Demo（双 Tab：单后端 SIWE / 多后端 UCAN+WebDAV）：
+  `examples/frontend/dapp.html`
+- 前端 TS 示例：`examples/frontend/main.ts`
+- 多语言后端示例：
+  - Node: `examples/backend/node/server.js`
+  - Go: `examples/backend/go/main.go`
+  - Java: `examples/backend/java/src/main/java/com/yeying/demo/AuthServer.java`
+  - Python: `examples/backend/python/app.py`
+
+## 本地联调
+
+1. 构建 SDK：`npm run build`
+2. 启动后端（示例）：
+   `./scripts/backend.sh start nodejs`
+3. 启动前端：
+   `python3 -m http.server 8001 --bind 127.0.0.1`
+4. 打开：
+   `http://127.0.0.1:8001/examples/frontend/dapp.html`
+
+多后端联调：
 
 ```bash
 ./scripts/backend.sh start all
-./scripts/backend.sh start all --setup
 ```
 
 默认端口：
@@ -85,37 +130,28 @@ npm install @yeying-community/web3-bs
 - Node `3203`
 - Python `3204`
 
-前端调用不同端口的后端时：
-- 将前端 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 授权后依次调用多个服务。
-
-## 常见问题
-
-### 刷新token失败
+## CORS 注意事项
 
-清理旧 Cookie 后重新登录：在浏览器 DevTools → Application → Cookies → http://127.0.0.1:8001 删除 refresh_token，再点 Login 后再点 Refresh Token。
+若你用 `http://[::]:8001` 打开页面，请确保后端 CORS 白名单包含该 Origin。  
+建议统一加入：
 
-### WebDAV 提示 invalid token
-
-报错示例：`authentication failed` / `invalid token`（通常来自 WebDAV 服务端鉴权中间件）。
+```bash
+CORS_ORIGINS=http://localhost:8001,http://127.0.0.1:8001,http://[::]:8001
+```
 
-排查与解决：
-- 确认 `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
+将本仓库作为本地依赖链接到你的 DApp：
 
-日志示例：
-```
-[2026-01-31T05:19:44.478Z] UCAN profile failed { error: 'UCAN audience mismatch' }
+```bash
+mkdir -p /path/to/your-dapp/node_modules/@yeying-community
+ln -s /path/to/web3-bs /path/to/your-dapp/node_modules/@yeying-community/web3-bs
 ```
 
-解决思路：
-- 生成 UCAN 时的 `audience` 必须与目标后端的 `UCAN_AUD` 完全一致。
-  - 例如 Node 后端：`did:web:127.0.0.1:3203`
-  - 例如 WebDAV 服务：`did:web:127.0.0.1:6065`
-- 多后端联调时，确保每个后端使用对应的 `audience` 生成 Invocation UCAN。
+## 文档导航
+
+- [文档导航](./docs/文档导航.md)
+- [快速上手](./docs/快速上手.md)
+- [SDK能力](./docs/SDK能力.md)
+- [移动端认证与授权选型指南](./docs/移动端认证与授权选型指南.md)
+- [接口规范（OpenAPI）](./docs/开放接口规范.yaml)

package/dist/auth/central.d.ts

@@ -0,0 +1,77 @@
+import type { AuthBaseOptions } from './types';
+import { type UcanCapability } from './ucan';
+export type CentralAuthBaseOptions = AuthBaseOptions & {
+    baseUrl?: string;
+    issuerPath?: string;
+    sessionPath?: string;
+    issuePath?: string;
+    accessToken?: string | null;
+    storeSessionToken?: boolean;
+    sessionTokenStorageKey?: string;
+};
+export type CentralIssuerInfo = {
+    enabled?: boolean;
+    issuerDid?: string;
+    defaultAudience?: string;
+    defaultCapabilities?: UcanCapability[];
+    response: unknown;
+};
+export type CreateCentralSessionOptions = CentralAuthBaseOptions & {
+    subject: string;
+    sessionTtlMs?: number;
+};
+export type CentralSessionResult = {
+    subject: string;
+    sessionToken: string;
+    expiresAt?: number;
+    issuerDid?: string;
+    response: unknown;
+};
+export type IssueCentralUcanOptions = CentralAuthBaseOptions & {
+    sessionToken?: string | null;
+    audience?: string;
+    capabilities?: UcanCapability[];
+    expiresInMs?: number;
+    ttlMs?: number;
+};
+export type CentralUcanIssueResult = {
+    ucan: string;
+    issuerDid?: string;
+    subject?: string;
+    audience?: string;
+    capabilities?: UcanCapability[];
+    exp?: number;
+    nbf?: number;
+    iat?: number;
+    response: unknown;
+};
+export type CreateAndIssueCentralUcanOptions = CentralAuthBaseOptions & {
+    subject: string;
+    sessionTtlMs?: number;
+    audience?: string;
+    capabilities?: UcanCapability[];
+    expiresInMs?: number;
+    ttlMs?: number;
+};
+export type CreateAndIssueCentralUcanResult = {
+    session: CentralSessionResult;
+    issue: CentralUcanIssueResult;
+};
+export type AuthCentralUcanFetchOptions = CentralAuthBaseOptions & {
+    ucan?: string | null;
+    sessionToken?: string | null;
+    subject?: string;
+    sessionTtlMs?: number;
+    audience?: string;
+    capabilities?: UcanCapability[];
+    expiresInMs?: number;
+    ttlMs?: number;
+};
+export declare function getCentralSessionToken(options?: CentralAuthBaseOptions): string | null;
+export declare function setCentralSessionToken(token: string | null, options?: CentralAuthBaseOptions): void;
+export declare function clearCentralSessionToken(options?: CentralAuthBaseOptions): void;
+export declare function getCentralIssuerInfo(options?: CentralAuthBaseOptions): Promise<CentralIssuerInfo>;
+export declare function createCentralSession(options: CreateCentralSessionOptions): Promise<CentralSessionResult>;
+export declare function issueCentralUcan(options?: IssueCentralUcanOptions): Promise<CentralUcanIssueResult>;
+export declare function createAndIssueCentralUcan(options: CreateAndIssueCentralUcanOptions): Promise<CreateAndIssueCentralUcanResult>;
+export declare function authCentralUcanFetch(input: RequestInfo | URL, init?: RequestInit, options?: AuthCentralUcanFetchOptions): Promise<Response>;

package/dist/auth/index.d.ts

@@ -2,3 +2,4 @@ export * from './types';
 export * from './provider';
 export * from './siwe';
 export * from './ucan';
+export * from './central';

package/dist/auth/ucan.d.ts

@@ -1,7 +1,10 @@
 import { Eip1193Provider } from './types';
 export type UcanCapability = {
-    resource: string;
-    action: string;
+    with?: string;
+    can?: string;
+    resource?: string;
+    action?: string;
+    nb?: unknown;
 };
 export type UcanRootProof = {
     type: 'siwe';
@@ -24,11 +27,15 @@ export type UcanTokenPayload = {
     nbf?: number;
     prf: UcanProof[];
 };
+export type UcanSessionSource = 'wallet' | 'local';
 export type UcanSessionRecord = {
     id: string;
     did: string;
     createdAt: number;
     expiresAt: number | null;
+    source?: UcanSessionSource;
+    privateKeyJwk?: JsonWebKey;
+    publicKeyJwk?: JsonWebKey;
     root?: UcanRootProof;
 };
 export type UcanSessionKey = {
@@ -36,6 +43,7 @@ export type UcanSessionKey = {
     did: string;
     createdAt: number;
     expiresAt: number | null;
+    source?: UcanSessionSource;
     signer?: (signingInput: string, payload: UcanTokenPayload) => Promise<string>;
     privateKey?: CryptoKey;
 };
@@ -81,6 +89,14 @@ export type UcanFetchOptions = {
     notBeforeMs?: number;
     fetcher?: typeof fetch;
 };
+export declare function getCapabilityResource(cap: UcanCapability | null | undefined): string;
+export declare function getCapabilityAction(cap: UcanCapability | null | undefined): string;
+export declare function normalizeUcanCapability(cap: UcanCapability | null | undefined, options?: {
+    includeLegacyAliases?: boolean;
+}): UcanCapability | null;
+export declare function normalizeUcanCapabilities(caps: UcanCapability[] | undefined, options?: {
+    includeLegacyAliases?: boolean;
+}): UcanCapability[];
 export declare function getUcanSession(id?: string, provider?: Eip1193Provider): Promise<UcanSessionKey | null>;
 export declare function createUcanSession(options?: CreateUcanSessionOptions): Promise<UcanSessionKey>;
 export declare function clearUcanSession(id?: string): Promise<void>;

package/dist/dapp.d.ts

@@ -45,5 +45,13 @@ export type InitDappSessionResult = {
     webdavToken?: string;
     webdavAppDir?: string;
 };
+export type AppIdLocationLike = {
+    host?: string | null;
+    hostname?: string | null;
+    port?: string | number | null;
+};
+export declare function normalizeAppHostnameForAppId(hostname: string): string;
+export declare function deriveAppIdFromHost(host: string): string;
+export declare function deriveAppIdFromLocation(locationLike?: AppIdLocationLike): string;
 export declare function initWebDavStorage(options: InitWebDavStorageOptions): Promise<InitWebDavStorageResult>;
 export declare function initDappSession(options: InitDappSessionOptions): Promise<InitDappSessionResult>;