@yeying-community/web3-bs 1.0.4 → 1.0.6

package/README.md

@@ -1,13 +1,15 @@
-# YeYing Inject Wallet SDK
+# YeYing Browser DApp Access SDK
 
-轻量级注入钱包 SDK，专注浏览器端 EIP-1193 Provider。默认优先选择 YeYing Wallet（支持 EIP-6963 多钱包发现）。
-仅支持浏览器环境（依赖 `window` / `localStorage` / `fetch`）。
+浏览器端 DApp 接入 SDK，用于统一封装钱包连接、会话维护、SIWE 登录、UCAN 多后端授权、中心化服务接入和 WebDAV 存储访问。
+它优先面向 EIP-1193 / EIP-6963 钱包生态，可对接 YeYing、MetaMask 等浏览器钱包；也可对接能暴露 EIP-1193 能力的 App 钱包或中心化认证服务。仅支持浏览器环境（依赖 `window` / `localStorage` / `fetch`）。
 
 功能要点：
 - 浏览器端 EIP-1193 Provider 辅助库
-- 默认优先 YeYing Wallet
+- 默认优先 YeYing Wallet，也兼容其他 EIP-1193 钱包
 - 内置 `signMessage` / `loginWithChallenge` / `refresh` / `logout` 等方法
 - 支持 UCAN Session + SIWE Bridge，用于多后端授权
+- 支持中心化 UCAN Demo API：`createCentralSession` / `issueCentralUcan` / `authCentralUcanFetch`
+- 统一封装前端连接会话、token 会话与 WebDAV 访问会话，降低 DApp 集成成本
 
 ## 安装
 
@@ -16,10 +18,24 @@ npm install @yeying-community/web3-bs
 ```
 
 更多集成与流程说明见 `docs/sdk-design.md`。
+推荐先读：
+- `docs/README.md`
+- `docs/positioning.md`
+- `docs/quickstart.md`
+- `docs/capability-matrix.md`
+
+## 接入路线
+
+- 钱包插件路线：适合浏览器内已有 YeYing、MetaMask 等插件钱包的 DApp；优先使用 `getProvider`、`loginWithChallenge`，并可扩展到 UCAN 多后端授权（钱包 UCAN RPC 优先，不支持时 SDK 自动回退本地 Ed25519 session）
+- App 钱包路线：适合移动端 Web；前提是钱包 App 或桥接层能暴露 EIP-1193 provider，通常使用 `requestAccounts`、`signMessage`、`loginWithChallenge`
+- 中心化服务路线：适合无钱包、无插件或更关注接入成本的场景；使用 JWT 或中心化 UCAN，通常组合 `setAccessToken`、`authFetch`、`createCentralSession`、`issueCentralUcan`
+
+能力对比见 `docs/capability-matrix.md`，详细接入步骤见 `docs/quickstart.md`。
 
 ## 示例
 
 - Frontend Dapp (HTML): `examples/frontend/dapp.html`
+- Frontend Mobile Central UCAN Demo: `examples/frontend/mobile-central-ucan.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`
@@ -90,9 +106,25 @@ npm install @yeying-community/web3-bs
 - UCAN 调用的 `audience` 与后端 `UCAN_AUD` 一致（如 `did:web:127.0.0.1:3202`）
 
 提示：`examples/frontend/dapp.html` 已内置多后端列表，可在一次 UCAN 授权后依次调用多个服务。
+提示：Demo 的 UCAN 流程按协议链路实现为 `Root（SIWE） -> Delegation -> Invocation`，便于按步骤理解多后端授权。
 
 ## 常见问题
 
+### 如何快速验证能力矩阵（钱包 UCAN + 本地回退）
+
+执行：
+
+```bash
+npm run check:capabilities
+```
+
+该脚本会自动验证：
+- 钱包 UCAN RPC 路径（`createUcanSession` 返回 `source=wallet`）
+- UCAN 本地回退路径（钱包不支持 `yeying_ucan_*` 时 `source=local`）
+- `createRootUcan` + `createInvocationUcan` 两条链路
+- `initWebDavStorage` 的 UCAN 自动初始化
+- 中心化 UCAN API 是否已导出（`createCentralSession` / `issueCentralUcan` / `authCentralUcanFetch`）
+
 ### 刷新token失败
 
 清理旧 Cookie 后重新登录：在浏览器 DevTools → Application → Cookies → http://127.0.0.1:8001 删除 refresh_token，再点 Login 后再点 Refresh Token。
@@ -103,8 +135,11 @@ npm install @yeying-community/web3-bs
 
 排查与解决：
 - 确认 `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`）。
+- `baseUrl` 不应包含任何路径；若服务挂载在子路径，请用 `prefix` 指定（例如 `/dav`）。
+- `audience` 必须与 WebDAV 服务端 `web3.ucan.audience` 一致（例如 `did:web:127.0.0.1:6065`）。
+- `capabilities` 与服务端要求一致（优先 `web3.ucan.required_capabilities`，兼容 `required_resource/required_action`）。
+  - SDK 推荐使用 `with/can`（兼容 `resource/action`），例如：`{ with: "app:all:<appId>", can: "read,write" }`。
+  - 推荐资源统一使用 `app:<scope>:<appId>`，常用为 `with=app:all:<appId>`；请确保路径在 `/apps/<appId>/`（或 `app_scope.path_prefix`）下。
 - Token 过期或缓存异常时，清理 UCAN 会话并重新登录/生成 Root + Invocation。
 
 ### UCAN audience mismatch

package/dist/auth/central.d.ts

@@ -0,0 +1,76 @@
+import type { AuthBaseOptions } from './types';
+import { type UcanCapability } from './ucan';
+export type CentralAuthBaseOptions = AuthBaseOptions & {
+    baseUrl?: string;
+    issuerPath?: string;
+    sessionPath?: string;
+    issuePath?: string;
+    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

@@ -8,6 +8,7 @@ export type InitWebDavStorageOptions = {
     prefix?: string;
     appDir?: string;
     appId?: string;
+    appAction?: string;
     ensureAppDir?: boolean;
     capabilities?: UcanCapability[];
     invocationCapabilities?: UcanCapability[];