@yeying-community/web3-bs 1.0.6 → 1.0.7

package/README.md

@@ -1,15 +1,14 @@
 # YeYing Browser DApp Access SDK
 
-浏览器端 DApp 接入 SDK，用于统一封装钱包连接、会话维护、SIWE 登录、UCAN 多后端授权、中心化服务接入和 WebDAV 存储访问。
-它优先面向 EIP-1193 / EIP-6963 钱包生态，可对接 YeYing、MetaMask 等浏览器钱包；也可对接能暴露 EIP-1193 能力的 App 钱包或中心化认证服务。仅支持浏览器环境（依赖 `window` / `localStorage` / `fetch`）。
+`web3-bs` 是浏览器端 DApp 接入 SDK，用于统一封装：
 
-功能要点：
-- 浏览器端 EIP-1193 Provider 辅助库
-- 默认优先 YeYing Wallet，也兼容其他 EIP-1193 钱包
-- 内置 `signMessage` / `loginWithChallenge` / `refresh` / `logout` 等方法
-- 支持 UCAN Session + SIWE Bridge，用于多后端授权
-- 支持中心化 UCAN Demo API：`createCentralSession` / `issueCentralUcan` / `authCentralUcanFetch`
-- 统一封装前端连接会话、token 会话与 WebDAV 访问会话，降低 DApp 集成成本
+- 钱包连接（EIP-1193 / EIP-6963）
+- SIWE challenge 登录与 JWT 鉴权请求
+- UCAN 多后端授权（钱包 UCAN RPC 优先，失败可回退本地 Ed25519 session）
+- 中心化 UCAN 发行服务接入
+- WebDAV 文件访问与应用目录初始化
+
+仅支持浏览器环境（依赖 `window` / `localStorage` / `fetch`）。
 
 ## 安装
 
@@ -17,82 +16,112 @@
 npm install @yeying-community/web3-bs
 ```
 
-更多集成与流程说明见 `docs/sdk-design.md`。
-推荐先读：
-- `docs/README.md`
-- `docs/positioning.md`
-- `docs/quickstart.md`
-- `docs/capability-matrix.md`
+## 能力概览
 
-## 接入路线
+### 1) Provider 与账户
 
-- 钱包插件路线：适合浏览器内已有 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`
+- `getProvider` / `requireProvider`
+- `requestAccounts` / `getAccounts` / `getPreferredAccount` / `watchAccounts`
+- `getChainId` / `getBalance`
+- `onAccountsChanged` / `onChainChanged`
 
-能力对比见 `docs/capability-matrix.md`，详细接入步骤见 `docs/quickstart.md`。
+### 2) SIWE + JWT
 
-## 示例
+- `signMessage`
+- `loginWithChallenge`
+- `authFetch`
+- `refreshAccessToken`
+- `logout`
+- `getAccessToken` / `setAccessToken` / `clearAccessToken`
 
-- 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`
-- Backend server (Python): `examples/backend/python/app.py`
-- Backend server (Java): `examples/backend/java/src/main/java/com/yeying/demo/AuthServer.java`
+### 3) UCAN（钱包优先 + 本地回退）
 
-## 本地验证
+- `createUcanSession` / `getUcanSession`
+- `getOrCreateUcanRoot` / `createRootUcan`
+- `createDelegationUcan` / `createInvocationUcan`
+- `authUcanFetch`
+- `normalizeUcanCapabilities`
 
-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`
+说明：
+- 能调用 `yeying_ucan_session` / `yeying_ucan_sign` 时，优先用钱包侧 UCAN session 签名。
+- 不支持上述钱包 RPC 时，SDK 会回退到浏览器本地 Ed25519 session（IndexedDB 持久化）。
 
-提示：如果前端来自其他域名，请设置
-`COOKIE_SAMESITE=none` 且 `COOKIE_SECURE=true` 并使用 HTTPS，
-以便 `refresh_token` Cookie 能随 `credentials: 'include'` 发送。
+### 4) 中心化 UCAN
 
-## 后端脚本用法
+- `getCentralIssuerInfo`
+- `createCentralSession`
+- `issueCentralUcan`
+- `createAndIssueCentralUcan`
+- `authCentralUcanFetch`
+- `getCentralSessionToken` / `setCentralSessionToken` / `clearCentralSessionToken`
 
-通用格式：
-`./scripts/backend.sh <start|stop|restart|status> <node|go|python|java|all> [--setup] [--no-stop]`
+### 5) WebDAV 与 DApp 会话编排
 
-示例：
-```bash
-# 启动 Node 后端
-./scripts/backend.sh start node
+- `createWebDavClient`
+- `initWebDavStorage`（自动生成/复用 WebDAV Invocation UCAN，可自动创建应用目录）
+- `initDappSession`（SIWE 登录 + WebDAV UCAN 初始化）
+- `deriveAppIdFromLocation` / `deriveAppIdFromHost`
 
-# 启动 Go 后端并安装依赖/构建
-./scripts/backend.sh start go --setup
+## 常见接入方式
 
-# 查看全部后端状态
-./scripts/backend.sh status all
+### 单后端登录（SIWE + JWT）
 
-# 重启 Python 后端
-./scripts/backend.sh restart python
+```ts
+import { loginWithChallenge, authFetch } from '@yeying-community/web3-bs';
 
-# 停止所有后端
-./scripts/backend.sh stop all
+await loginWithChallenge({
+  baseUrl: 'http://localhost:3203/api/v1/public/auth',
+  storeToken: false,
+});
 
-# 同时启动多个后端（不停止已运行的服务）
-./scripts/backend.sh start all --no-stop
+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
+
+- 前端 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`
 
-可同时启动多语言后端（不同端口），验证 UCAN 多后端授权：
+多后端联调：
 
 ```bash
 ./scripts/backend.sh start all
-./scripts/backend.sh start all --setup
 ```
 
 默认端口：
@@ -101,56 +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 授权后依次调用多个服务。
-提示：Demo 的 UCAN 流程按协议链路实现为 `Root（SIWE） -> Delegation -> Invocation`，便于按步骤理解多后端授权。
-
-## 常见问题
+## CORS 注意事项
 
-### 如何快速验证能力矩阵（钱包 UCAN + 本地回退）
-
-执行：
+若你用 `http://[::]:8001` 打开页面，请确保后端 CORS 白名单包含该 Origin。  
+建议统一加入：
 
 ```bash
-npm run check:capabilities
+CORS_ORIGINS=http://localhost:8001,http://127.0.0.1:8001,http://[::]:8001
 ```
 
-该脚本会自动验证：
-- 钱包 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。
+## 本地软链接（开发）
 
-### WebDAV 提示 invalid token
+将本仓库作为本地依赖链接到你的 DApp：
 
-报错示例：`authentication failed` / `invalid token`（通常来自 WebDAV 服务端鉴权中间件）。
-
-排查与解决：
-- 确认 `baseUrl` 指向 WebDAV 服务（默认 `http://127.0.0.1:6065`），不要误用 320x 认证后端。
-- `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
-
-日志示例：
-```
-[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

@@ -5,6 +5,7 @@ export type CentralAuthBaseOptions = AuthBaseOptions & {
     issuerPath?: string;
     sessionPath?: string;
     issuePath?: string;
+    accessToken?: string | null;
     storeSessionToken?: boolean;
     sessionTokenStorageKey?: string;
 };

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>;

package/dist/web3-bs.esm.js

@@ -1131,6 +1131,16 @@ function resolveCredentials(options) {
 function resolveSessionTokenKey(options) {
     return options?.sessionTokenStorageKey || DEFAULT_SESSION_TOKEN_KEY;
 }
+function resolveAccessToken(options) {
+    if (typeof options?.accessToken === 'string') {
+        const token = options.accessToken.trim();
+        return token || null;
+    }
+    if (options?.accessToken === null) {
+        return null;
+    }
+    return getAccessToken(options);
+}
 function shouldStoreSessionToken(options) {
     return options?.storeSessionToken !== false;
 }
@@ -1178,6 +1188,9 @@ function parseCapabilitiesField(obj, keys) {
     }
     return undefined;
 }
+function parseIssuerDidField(obj) {
+    return parseStringField(obj, ['issuerDid', 'issuer', 'did']);
+}
 function readStoredSessionToken(options) {
     if (!shouldStoreSessionToken(options))
         return null;
@@ -1234,11 +1247,16 @@ async function getCentralIssuerInfo(options = {}) {
     const fetcher = resolveFetcher(options);
     const credentials = resolveCredentials(options);
     const url = joinUrl$1(resolveBaseUrl(options), options.issuerPath || DEFAULT_ISSUER_PATH);
+    const token = resolveAccessToken(options);
+    const headers = new Headers({
+        accept: 'application/json',
+    });
+    if (token) {
+        headers.set('Authorization', `Bearer ${token}`);
+    }
     const response = await fetcher(url, {
         method: 'GET',
-        headers: {
-            accept: 'application/json',
-        },
+        headers,
         credentials,
     });
     const payload = await parseJsonBody(response);
@@ -1248,7 +1266,7 @@ async function getCentralIssuerInfo(options = {}) {
     const data = parseEnvelopeData(payload);
     return {
         enabled: typeof data.enabled === 'boolean' ? data.enabled : undefined,
-        issuerDid: parseStringField(data, ['issuerDid']),
+        issuerDid: parseIssuerDidField(data),
         defaultAudience: parseStringField(data, ['defaultAudience']),
         defaultCapabilities: parseCapabilitiesField(data, ['defaultCapabilities']),
         response: payload,
@@ -1261,13 +1279,18 @@ async function createCentralSession(options) {
     }
     const fetcher = resolveFetcher(options);
     const credentials = resolveCredentials(options);
+    const accessToken = resolveAccessToken(options);
     const url = joinUrl$1(resolveBaseUrl(options), options.sessionPath || DEFAULT_SESSION_PATH);
+    const headers = new Headers({
+        'Content-Type': 'application/json',
+        accept: 'application/json',
+    });
+    if (accessToken) {
+        headers.set('Authorization', `Bearer ${accessToken}`);
+    }
     const response = await fetcher(url, {
         method: 'POST',
-        headers: {
-            'Content-Type': 'application/json',
-            accept: 'application/json',
-        },
+        headers,
         credentials,
         body: JSON.stringify({
             subject,
@@ -1288,7 +1311,7 @@ async function createCentralSession(options) {
         subject: parseStringField(data, ['subject']) || subject,
         sessionToken,
         expiresAt: parseNumberField(data, ['expiresAt']),
-        issuerDid: parseStringField(data, ['issuerDid']),
+        issuerDid: parseIssuerDidField(data),
         response: payload,
     };
 }
@@ -1329,13 +1352,13 @@ async function issueCentralUcan(options = {}) {
     }
     return {
         ucan,
-        issuerDid: parseStringField(data, ['issuerDid']),
+        issuerDid: parseIssuerDidField(data),
         subject: parseStringField(data, ['subject']),
         audience: parseStringField(data, ['audience']),
         capabilities: parseCapabilitiesField(data, ['capabilities']),
-        exp: parseNumberField(data, ['exp']),
-        nbf: parseNumberField(data, ['nbf']),
-        iat: parseNumberField(data, ['iat']),
+        exp: parseNumberField(data, ['exp', 'expiresAt']),
+        nbf: parseNumberField(data, ['nbf', 'notBefore']),
+        iat: parseNumberField(data, ['iat', 'issuedAt']),
         response: payload,
     };
 }
@@ -1608,6 +1631,13 @@ function createWebDavClient(options) {
 const tokenCache = new Map();
 const TOKEN_SKEW_MS = 5000;
 const DEFAULT_APP_ACTION = 'write';
+const LOOPBACK_HOST_ALIASES = new Set([
+    'localhost',
+    '127.0.0.1',
+    '::1',
+    '0:0:0:0:0:0:0:1',
+    '0.0.0.0',
+]);
 function normalizeAppDir(path) {
     const trimmed = path.trim();
     if (!trimmed)
@@ -1619,6 +1649,69 @@ function normalizeAppDir(path) {
 function sanitizeAppId(appId) {
     return appId.trim().replace(/[^a-zA-Z0-9._-]/g, '-');
 }
+function parseHostPort(rawHost) {
+    const host = rawHost.trim();
+    if (!host)
+        return { hostname: '', port: '' };
+    const bracketMatch = host.match(/^\[([^\]]+)\](?::([0-9]+))?$/);
+    if (bracketMatch) {
+        return {
+            hostname: bracketMatch[1] || '',
+            port: bracketMatch[2] || '',
+        };
+    }
+    const firstColon = host.indexOf(':');
+    const lastColon = host.lastIndexOf(':');
+    if (firstColon > -1 && firstColon === lastColon) {
+        const hostname = host.slice(0, firstColon).trim();
+        const port = host.slice(firstColon + 1).trim();
+        if (/^[0-9]+$/.test(port)) {
+            return { hostname, port };
+        }
+    }
+    return { hostname: host, port: '' };
+}
+function normalizeAppHostnameForAppId(hostname) {
+    const normalized = (hostname || '').trim().toLowerCase();
+    if (!normalized)
+        return '';
+    const bare = normalized.replace(/^\[(.*)\]$/, '$1');
+    if (LOOPBACK_HOST_ALIASES.has(normalized) || LOOPBACK_HOST_ALIASES.has(bare)) {
+        return 'localhost';
+    }
+    return bare;
+}
+function buildSanitizedAppId(hostname, port) {
+    const normalizedHostname = normalizeAppHostnameForAppId(hostname);
+    if (!normalizedHostname)
+        return '';
+    const normalizedPort = port === undefined || port === null ? '' : String(port).trim();
+    const host = normalizedPort
+        ? `${normalizedHostname}:${normalizedPort}`
+        : normalizedHostname;
+    return sanitizeAppId(host);
+}
+function deriveAppIdFromHost(host) {
+    const parsed = parseHostPort(host || '');
+    return buildSanitizedAppId(parsed.hostname, parsed.port);
+}
+function deriveAppIdFromLocation(locationLike) {
+    const source = locationLike ||
+        (typeof window !== 'undefined' ? window.location : undefined);
+    if (!source)
+        return '';
+    const hostname = typeof source.hostname === 'string' ? source.hostname : '';
+    const port = source.port;
+    if (hostname) {
+        const appId = buildSanitizedAppId(hostname, port);
+        if (appId)
+            return appId;
+    }
+    if (typeof source.host === 'string') {
+        return deriveAppIdFromHost(source.host);
+    }
+    return '';
+}
 function normalizeAction(action) {
     const trimmed = (action || '').trim();
     return trimmed ? trimmed : null;
@@ -1842,5 +1935,5 @@ async function initDappSession(options) {
     return result;
 }
 
-export { WebDavClient, authCentralUcanFetch, authFetch, authUcanFetch, clearAccessToken, clearCentralSessionToken, clearUcanSession, createAndIssueCentralUcan, createCentralSession, createDelegationUcan, createInvocationUcan, createRootUcan, createUcanSession, createWebDavClient, getAccessToken, getAccounts, getBalance, getCapabilityAction, getCapabilityResource, getCentralIssuerInfo, getCentralSessionToken, getChainId, getOrCreateUcanRoot, getPreferredAccount, getProvider, getStoredUcanRoot, getUcanSession, initDappSession, initWebDavStorage, isYeYingProvider, issueCentralUcan, loginWithChallenge, logout, normalizeUcanCapabilities, normalizeUcanCapability, onAccountsChanged, onChainChanged, refreshAccessToken, requestAccounts, requireProvider, setAccessToken, setCentralSessionToken, signMessage, storeUcanRoot, watchAccounts };
+export { WebDavClient, authCentralUcanFetch, authFetch, authUcanFetch, clearAccessToken, clearCentralSessionToken, clearUcanSession, createAndIssueCentralUcan, createCentralSession, createDelegationUcan, createInvocationUcan, createRootUcan, createUcanSession, createWebDavClient, deriveAppIdFromHost, deriveAppIdFromLocation, getAccessToken, getAccounts, getBalance, getCapabilityAction, getCapabilityResource, getCentralIssuerInfo, getCentralSessionToken, getChainId, getOrCreateUcanRoot, getPreferredAccount, getProvider, getStoredUcanRoot, getUcanSession, initDappSession, initWebDavStorage, isYeYingProvider, issueCentralUcan, loginWithChallenge, logout, normalizeAppHostnameForAppId, normalizeUcanCapabilities, normalizeUcanCapability, onAccountsChanged, onChainChanged, refreshAccessToken, requestAccounts, requireProvider, setAccessToken, setCentralSessionToken, signMessage, storeUcanRoot, watchAccounts };
 //# sourceMappingURL=web3-bs.esm.js.map