@yeying-community/web3-bs 1.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2020 YeYing Community
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,265 @@
+# YeYing Inject Wallet SDK
+
+轻量级注入钱包 SDK，专注浏览器端 EIP-1193 Provider。默认优先选择 YeYing Wallet（支持 EIP-6963 多钱包发现）。
+仅支持浏览器环境（依赖 `window` / `localStorage` / `fetch`）。
+
+## 安装
+
+```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`）。
+
+## 示例
+
+- 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`
+
+## 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?)`
+
+示例：
+```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());
+```
+
+后端默认要求的能力为 `resource=profile`、`action=read`，可通过环境变量覆盖：
+- `UCAN_AUD`：服务 DID（默认 `did:web:localhost:3203`）
+- `UCAN_RESOURCE`：资源（默认 `profile`）
+- `UCAN_ACTION`：动作（默认 `read`）
+
+提示：如需可转授权，使用 `createDelegationUcan` 创建委任链，再用被委任的 Key 生成 Invocation UCAN。
+
+## WebDAV 存储（Storage）
+
+提供基于 WebDAV 服务的文件操作封装（上传/下载/删除/目录等），适配 `webdav` 项目 API。
+
+示例：
+```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');
+```
+
+常用方法：
+- `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()`
+
+## 本地验证
+
+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`
+
+提示：如果前端来自其他域名，请设置
+`COOKIE_SAMESITE=none` 且 `COOKIE_SECURE=true` 并使用 HTTPS，
+以便 `refresh_token` Cookie 能随 `credentials: 'include'` 发送。
+
+## 多后端联调（不同端口）
+
+可同时启动多语言后端（不同端口），验证 UCAN 多后端授权：
+
+```bash
+./scripts/backend.sh start all
+./scripts/backend.sh start all --setup
+```
+
+默认端口：
+- Go `3201`
+- Java `3202`
+- Node `3203`
+- Python `3204`
+
+前端调用不同端口的后端时：
+- 将前端 Origin 加入 `CORS_ORIGINS`（例如 `http://localhost:3203`）
+- UCAN 调用的 `audience` 与后端 `UCAN_AUD` 一致（如 `did:web:localhost:3202`）
+
+提示：`examples/frontend/dapp.html` 已内置多后端列表，可在一次 UCAN 授权后依次调用多个服务。
+
+## 常见问题
+
+### 刷新token失败
+
+清理旧 Cookie 后重新登录：在浏览器 DevTools → Application → Cookies → http://localhost:8001 删除 refresh_token，再点 Login 后再点 Refresh Token。

package/dist/auth/index.d.ts

@@ -0,0 +1,4 @@
+export * from './types';
+export * from './provider';
+export * from './siwe';
+export * from './ucan';

package/dist/auth/provider.d.ts

@@ -0,0 +1,10 @@
+import { Eip1193Provider, ProviderDiscoveryOptions, ProviderInfo, RequestAccountsOptions } 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 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/siwe.d.ts

@@ -0,0 +1,17 @@
+import { AuthBaseOptions, AuthFetchOptions, AuthTokenResult, LoginWithChallengeOptions, LogoutOptions, RefreshAccessTokenOptions, SignMessageOptions } from './types';
+export declare function getAccessToken(options?: AuthBaseOptions): string | null;
+export declare function setAccessToken(token: string | null, options?: AuthBaseOptions): void;
+export declare function clearAccessToken(options?: AuthBaseOptions): void;
+export declare function signMessage(options: SignMessageOptions): Promise<string>;
+export declare function loginWithChallenge(options?: LoginWithChallengeOptions): Promise<{
+    token: string;
+    address: string;
+    signature: string;
+    challenge: string;
+    response: unknown;
+}>;
+export declare function refreshAccessToken(options?: RefreshAccessTokenOptions): Promise<AuthTokenResult>;
+export declare function logout(options?: LogoutOptions): Promise<{
+    response: unknown;
+}>;
+export declare function authFetch(input: RequestInfo | URL, init?: RequestInit, options?: AuthFetchOptions): Promise<Response>;

package/dist/auth/types.d.ts

@@ -0,0 +1,71 @@
+export type JsonRpcRequest = {
+    method: string;
+    params?: unknown[] | Record<string, unknown>;
+};
+export interface Eip1193Provider {
+    request: (args: JsonRpcRequest) => Promise<unknown>;
+    on?: {
+        (event: 'accountsChanged', listener: (accounts: string[]) => void): void;
+        (event: 'chainChanged', listener: (chainId: string) => void): void;
+        (event: string, listener: (...args: unknown[]) => void): void;
+    };
+    removeListener?: {
+        (event: 'accountsChanged', listener: (accounts: string[]) => void): void;
+        (event: 'chainChanged', listener: (chainId: string) => void): void;
+        (event: string, listener: (...args: unknown[]) => void): void;
+    };
+    isMetaMask?: boolean;
+    isYeYing?: boolean;
+}
+export interface ProviderInfo {
+    uuid?: string;
+    name?: string;
+    icon?: string;
+    rdns?: string;
+}
+export interface Eip6963ProviderDetail {
+    info: ProviderInfo;
+    provider: Eip1193Provider;
+}
+export interface ProviderDiscoveryOptions {
+    timeoutMs?: number;
+    preferYeYing?: boolean;
+}
+export interface RequestAccountsOptions {
+    provider?: Eip1193Provider;
+}
+export interface SignMessageOptions {
+    provider?: Eip1193Provider;
+    message: string;
+    address?: string;
+    method?: 'personal_sign' | 'eth_sign';
+}
+export interface AuthBaseOptions {
+    baseUrl?: string;
+    fetcher?: typeof fetch;
+    credentials?: RequestCredentials;
+    storeToken?: boolean;
+    tokenStorageKey?: string;
+}
+export interface LoginWithChallengeOptions extends AuthBaseOptions {
+    provider?: Eip1193Provider;
+    address?: string;
+    challengePath?: string;
+    verifyPath?: string;
+    signMethod?: 'personal_sign' | 'eth_sign';
+}
+export interface RefreshAccessTokenOptions extends AuthBaseOptions {
+    refreshPath?: string;
+}
+export interface LogoutOptions extends AuthBaseOptions {
+    logoutPath?: string;
+}
+export interface AuthFetchOptions extends AuthBaseOptions {
+    refreshPath?: string;
+    accessToken?: string | null;
+    retryOnUnauthorized?: boolean;
+}
+export interface AuthTokenResult {
+    token: string;
+    response: unknown;
+}

package/dist/auth/ucan.d.ts

@@ -0,0 +1,92 @@
+import { Eip1193Provider } from './types';
+export type UcanCapability = {
+    resource: string;
+    action: string;
+};
+export type UcanRootProof = {
+    type: 'siwe';
+    iss: string;
+    aud: string;
+    cap: UcanCapability[];
+    exp: number;
+    nbf?: number;
+    siwe: {
+        message: string;
+        signature: string;
+    };
+};
+export type UcanProof = UcanRootProof | string;
+export type UcanTokenPayload = {
+    iss: string;
+    aud: string;
+    cap: UcanCapability[];
+    exp: number;
+    nbf?: number;
+    prf: UcanProof[];
+};
+export type UcanSessionRecord = {
+    id: string;
+    did: string;
+    createdAt: number;
+    expiresAt: number | null;
+    root?: UcanRootProof;
+};
+export type UcanSessionKey = {
+    id: string;
+    did: string;
+    createdAt: number;
+    expiresAt: number | null;
+    signer?: (signingInput: string, payload: UcanTokenPayload) => Promise<string>;
+    privateKey?: CryptoKey;
+};
+export type CreateUcanSessionOptions = {
+    id?: string;
+    expiresInMs?: number;
+    forceNew?: boolean;
+    provider?: Eip1193Provider;
+};
+export type CreateRootUcanOptions = {
+    provider?: Eip1193Provider;
+    address?: string;
+    session?: UcanSessionKey;
+    sessionId?: string;
+    capabilities: UcanCapability[];
+    expiresInMs?: number;
+    domain?: string;
+    uri?: string;
+    chainId?: string;
+    statement?: string;
+    nonce?: string;
+    notBeforeMs?: number;
+};
+export type CreateUcanTokenOptions = {
+    issuer?: UcanSessionKey;
+    sessionId?: string;
+    provider?: Eip1193Provider;
+    audience: string;
+    capabilities: UcanCapability[];
+    expiresInMs?: number;
+    notBeforeMs?: number;
+    proofs?: UcanProof[];
+};
+export type UcanFetchOptions = {
+    ucan?: string;
+    audience?: string;
+    capabilities?: UcanCapability[];
+    issuer?: UcanSessionKey;
+    sessionId?: string;
+    provider?: Eip1193Provider;
+    proofs?: UcanProof[];
+    expiresInMs?: number;
+    notBeforeMs?: number;
+    fetcher?: typeof fetch;
+};
+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>;
+export declare function storeUcanRoot(root: UcanRootProof, id?: string): Promise<void>;
+export declare function getStoredUcanRoot(id?: string): Promise<UcanRootProof | null>;
+export declare function createRootUcan(options: CreateRootUcanOptions): Promise<UcanRootProof>;
+export declare function createDelegationUcan(options: CreateUcanTokenOptions): Promise<string>;
+export declare function createInvocationUcan(options: CreateUcanTokenOptions): Promise<string>;
+export declare function authUcanFetch(input: RequestInfo | URL, init?: RequestInit, options?: UcanFetchOptions): Promise<Response>;

package/dist/index.d.ts

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

package/dist/storage/index.d.ts

@@ -0,0 +1 @@
+export * from './webdav';

package/dist/storage/webdav.d.ts

@@ -0,0 +1,54 @@
+export type WebDavAuth = {
+    type: 'bearer';
+    token: string;
+} | {
+    type: 'basic';
+    username: string;
+    password: string;
+};
+export type WebDavClientOptions = {
+    baseUrl: string;
+    prefix?: string;
+    auth?: WebDavAuth;
+    token?: string;
+    fetcher?: typeof fetch;
+    credentials?: RequestCredentials;
+};
+export type WebDavRequestOptions = {
+    headers?: Record<string, string>;
+    auth?: WebDavAuth;
+    token?: string;
+    depth?: number | 'infinity';
+    overwrite?: boolean;
+    contentType?: string;
+    signal?: AbortSignal;
+};
+export declare class WebDavClient {
+    private baseUrl;
+    private prefix;
+    private auth?;
+    private token?;
+    private fetcher;
+    private credentials?;
+    constructor(options: WebDavClientOptions);
+    setToken(token: string | null): void;
+    setAuth(auth?: WebDavAuth): void;
+    private buildUrl;
+    private buildHeaders;
+    request(method: string, path: string, body?: BodyInit | null, options?: WebDavRequestOptions): Promise<Response>;
+    listDirectory(path?: string, depth?: number | 'infinity'): Promise<string>;
+    download(path: string): Promise<Response>;
+    downloadText(path: string): Promise<string>;
+    downloadArrayBuffer(path: string): Promise<ArrayBuffer>;
+    upload(path: string, content: BodyInit, contentType?: string): Promise<Response>;
+    createDirectory(path: string): Promise<Response>;
+    remove(path: string): Promise<Response>;
+    move(path: string, destination: string, overwrite?: boolean): Promise<Response>;
+    copy(path: string, destination: string, overwrite?: boolean): Promise<Response>;
+    getQuota(): Promise<unknown>;
+    listRecycle(): Promise<unknown>;
+    recoverRecycle(hash: string): Promise<unknown>;
+    deleteRecycle(hash: string): Promise<unknown>;
+    clearRecycle(): Promise<unknown>;
+}
+export declare function createWebDavClient(options: WebDavClientOptions): WebDavClient;