@yeying-community/web3-bs 1.0.11 → 1.0.12

package/dist/auth/ucan.d.ts

@@ -77,6 +77,11 @@ export type CreateUcanTokenOptions = {
     notBeforeMs?: number;
     proofs?: UcanProof[];
 };
+export type GetOrCreateInvocationUcanOptions = CreateUcanTokenOptions & {
+    ucan?: string;
+    skewMs?: number;
+    nowMs?: number;
+};
 export type UcanFetchOptions = {
     ucan?: string;
     audience?: string;
@@ -87,8 +92,37 @@ export type UcanFetchOptions = {
     proofs?: UcanProof[];
     expiresInMs?: number;
     notBeforeMs?: number;
+    skewMs?: number;
     fetcher?: typeof fetch;
 };
+export type UcanTokenTiming = {
+    valid: boolean;
+    payload: UcanTokenPayload | null;
+    exp: number | null;
+    nbf: number | null;
+    issuedAt: number | null;
+    nowMs: number;
+    remainingMs: number | null;
+    activeInMs: number;
+    expired: boolean;
+    notBefore: boolean;
+};
+export type UcanTtlPolicy = {
+    expiresInMs?: number;
+    skewMs?: number;
+};
+export type UcanAuthErrorType = 'expired' | 'not-before' | 'unauthorized' | 'forbidden' | 'invalid-token' | 'unknown';
+export type UcanAuthErrorInfo = {
+    type: UcanAuthErrorType;
+    message: string;
+    retryable: boolean;
+    shouldRefresh: boolean;
+    status?: number;
+    code?: string | number;
+};
+export declare const DEFAULT_UCAN_SESSION_TTL_MS: number;
+export declare const DEFAULT_UCAN_TOKEN_TTL_MS: number;
+export declare const DEFAULT_UCAN_TOKEN_SKEW_MS: number;
 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?: {
@@ -97,6 +131,15 @@ export declare function normalizeUcanCapability(cap: UcanCapability | null | und
 export declare function normalizeUcanCapabilities(caps: UcanCapability[] | undefined, options?: {
     includeLegacyAliases?: boolean;
 }): UcanCapability[];
+export declare function normalizeUcanExpiry(exp: number | undefined, fallbackMs: number): number;
+export declare function decodeUcanPayload(token: string): UcanTokenPayload | null;
+export declare function getUcanTokenTiming(token: string, options?: {
+    nowMs?: number;
+}): UcanTokenTiming;
+export declare function isUcanTokenFresh(tokenOrTiming: string | UcanTokenTiming, options?: UcanTtlPolicy & {
+    nowMs?: number;
+}): boolean;
+export declare function classifyUcanAuthError(error: unknown): UcanAuthErrorInfo;
 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>;
@@ -106,4 +149,5 @@ export declare function getOrCreateUcanRoot(options: CreateRootUcanOptions): Pro
 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 getOrCreateInvocationUcan(options: GetOrCreateInvocationUcanOptions): Promise<string>;
 export declare function authUcanFetch(input: RequestInfo | URL, init?: RequestInit, options?: UcanFetchOptions): Promise<Response>;

package/dist/dapp.d.ts

@@ -18,6 +18,7 @@ export type InitWebDavStorageOptions = {
     root?: UcanRootProof;
     rootExpiresInMs?: number;
     invocationExpiresInMs?: number;
+    invocationSkewMs?: number;
     notBeforeMs?: number;
     fetcher?: typeof fetch;
     credentials?: RequestCredentials;

package/dist/web3-bs.esm.js

@@ -688,8 +688,9 @@ async function authFetch(input, init = {}, options = {}) {
 }
 
 const DEFAULT_SESSION_ID = 'default';
-const DEFAULT_SESSION_TTL = 24 * 60 * 60 * 1000;
-const DEFAULT_UCAN_TTL = 5 * 60 * 1000;
+const DEFAULT_UCAN_SESSION_TTL_MS = 24 * 60 * 60 * 1000;
+const DEFAULT_UCAN_TOKEN_TTL_MS = 40 * 60 * 1000;
+const DEFAULT_UCAN_TOKEN_SKEW_MS = 60 * 1000;
 const DB_NAME = 'yeying-web3';
 const DB_STORE = 'ucan-sessions';
 const BASE58_ALPHABET = '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz';
@@ -770,6 +771,30 @@ function normalizeUcanCapabilities(caps, options = {}) {
 function encodeJson(value) {
     return toBase64Url(textEncoder.encode(JSON.stringify(value)));
 }
+function decodeBase64Url(input) {
+    if (!input)
+        return null;
+    const base64 = input.replace(/-/g, '+').replace(/_/g, '/');
+    const padded = base64.padEnd(Math.ceil(base64.length / 4) * 4, '=');
+    try {
+        if (typeof atob === 'function') {
+            return atob(padded);
+        }
+    }
+    catch {
+        // Try Node-compatible fallback below.
+    }
+    try {
+        const nodeBuffer = globalThis.Buffer;
+        if (nodeBuffer) {
+            return nodeBuffer.from(padded, 'base64').toString('utf8');
+        }
+    }
+    catch {
+        return null;
+    }
+    return null;
+}
 function randomNonce(bytes = 16) {
     const buffer = new Uint8Array(bytes);
     crypto.getRandomValues(buffer);
@@ -778,8 +803,144 @@ function randomNonce(bytes = 16) {
         .join('');
 }
 function normalizeExpiry(exp, fallbackMs) {
+    if (typeof exp === 'number' && !Number.isNaN(exp))
+        return exp;
     return Date.now() + fallbackMs;
 }
+function normalizeUcanExpiry(exp, fallbackMs) {
+    return normalizeExpiry(exp, fallbackMs);
+}
+function decodeUcanPayload(token) {
+    const parts = String(token || '').split('.');
+    if (parts.length < 2)
+        return null;
+    const decoded = decodeBase64Url(parts[1]);
+    if (!decoded)
+        return null;
+    try {
+        const payload = JSON.parse(decoded);
+        if (!payload || typeof payload !== 'object')
+            return null;
+        return payload;
+    }
+    catch {
+        return null;
+    }
+}
+function getUcanTokenTiming(token, options = {}) {
+    const nowMs = options.nowMs ?? Date.now();
+    const payload = decodeUcanPayload(token);
+    const exp = typeof payload?.exp === 'number' ? payload.exp : null;
+    const nbf = typeof payload?.nbf === 'number' ? payload.nbf : null;
+    const payloadWithIat = payload;
+    const issuedAt = typeof payloadWithIat?.iat === 'number'
+        ? payloadWithIat.iat
+        : null;
+    const remainingMs = exp === null ? null : exp - nowMs;
+    const activeInMs = nbf === null ? 0 : Math.max(0, nbf - nowMs);
+    const expired = exp === null || (remainingMs !== null && remainingMs <= 0);
+    const notBefore = activeInMs > 0;
+    return {
+        valid: Boolean(payload && !expired && !notBefore),
+        payload,
+        exp,
+        nbf,
+        issuedAt,
+        nowMs,
+        remainingMs,
+        activeInMs,
+        expired,
+        notBefore,
+    };
+}
+function isUcanTokenFresh(tokenOrTiming, options = {}) {
+    const timing = typeof tokenOrTiming === 'string'
+        ? getUcanTokenTiming(tokenOrTiming, { nowMs: options.nowMs })
+        : tokenOrTiming;
+    if (!timing.valid)
+        return false;
+    const skewMs = Math.max(0, options.skewMs ?? DEFAULT_UCAN_TOKEN_SKEW_MS);
+    return typeof timing.remainingMs === 'number' && timing.remainingMs > skewMs;
+}
+function readErrorField(error, field) {
+    if (!error || typeof error !== 'object')
+        return undefined;
+    const value = error[field];
+    if (value !== undefined)
+        return value;
+    const nestedError = error.error;
+    if (nestedError && typeof nestedError === 'object') {
+        return nestedError[field];
+    }
+    return undefined;
+}
+function classifyUcanAuthError(error) {
+    const messageValue = readErrorField(error, 'message');
+    const codeValue = readErrorField(error, 'code');
+    const statusValue = readErrorField(error, 'status') ?? readErrorField(error, 'statusCode');
+    const message = typeof messageValue === 'string'
+        ? messageValue
+        : error instanceof Error
+            ? error.message
+            : String(messageValue || error || '');
+    const status = typeof statusValue === 'number' ? statusValue : undefined;
+    const code = typeof codeValue === 'string' || typeof codeValue === 'number' ? codeValue : undefined;
+    const normalized = `${message} ${String(code || '')}`.toLowerCase();
+    if (/ucan.*expired|expired.*ucan|token.*expired|jwt.*expired|\bexp\b/.test(normalized)) {
+        return { type: 'expired', message, retryable: true, shouldRefresh: true, status, code };
+    }
+    if (/not.?before|\bnbf\b|not yet valid/.test(normalized)) {
+        return { type: 'not-before', message, retryable: true, shouldRefresh: false, status, code };
+    }
+    if (/invalid.*token|malformed.*token|bad.*ucan|invalid.*ucan/.test(normalized)) {
+        return { type: 'invalid-token', message, retryable: true, shouldRefresh: true, status, code };
+    }
+    if (status === 401 || /unauthori[sz]ed|unauthenticated/.test(normalized)) {
+        return { type: 'unauthorized', message, retryable: true, shouldRefresh: true, status, code };
+    }
+    if (status === 403 || /forbidden|permission denied|capability/.test(normalized)) {
+        return { type: 'forbidden', message, retryable: false, shouldRefresh: false, status, code };
+    }
+    return { type: 'unknown', message, retryable: false, shouldRefresh: false, status, code };
+}
+function isReplayableRequestBody(body) {
+    if (body == null)
+        return true;
+    if (typeof body === 'string')
+        return true;
+    if (typeof URLSearchParams !== 'undefined' && body instanceof URLSearchParams)
+        return true;
+    if (typeof FormData !== 'undefined' && body instanceof FormData)
+        return true;
+    if (typeof Blob !== 'undefined' && body instanceof Blob)
+        return true;
+    if (body instanceof ArrayBuffer)
+        return true;
+    if (ArrayBuffer.isView(body))
+        return true;
+    return false;
+}
+async function parseResponseJsonBody(response) {
+    const text = await response.text();
+    if (!text)
+        return null;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return { raw: text };
+    }
+}
+function shouldRetryUcanFetch(response, errorInfo) {
+    if (errorInfo.type === 'expired' || errorInfo.shouldRefresh) {
+        return true;
+    }
+    if (response.status === 401)
+        return true;
+    if (response.status === 403 && errorInfo.type === 'forbidden')
+        return false;
+    return false;
+}
 function isSessionExpired(expiresAt, nowMs = Date.now()) {
     return typeof expiresAt === 'number' && nowMs >= expiresAt;
 }
@@ -876,7 +1037,7 @@ async function createLocalSession(options, record) {
         buildDidKey(pair.publicKey),
     ]);
     const createdAt = Date.now();
-    const expiresAt = normalizeExpiry(undefined, options.expiresInMs ?? DEFAULT_SESSION_TTL);
+    const expiresAt = normalizeExpiry(undefined, options.expiresInMs ?? DEFAULT_UCAN_SESSION_TTL_MS);
     const root = shouldKeepRootForSession(record?.root, did, createdAt) ? record?.root : undefined;
     await writeSessionRecord({
         id: sessionId,
@@ -1144,7 +1305,7 @@ async function createRootUcan(options) {
     const domain = options.domain || (typeof window !== 'undefined' ? window.location.host : '127.0.0.1');
     const uri = options.uri || (typeof window !== 'undefined' ? window.location.origin : 'http://127.0.0.1');
     const nonce = options.nonce || randomNonce(8);
-    const exp = normalizeExpiry(undefined, options.expiresInMs ?? DEFAULT_SESSION_TTL);
+    const exp = normalizeExpiry(undefined, options.expiresInMs ?? DEFAULT_UCAN_SESSION_TTL_MS);
     const nbf = options.notBeforeMs;
     const normalizedCapabilities = normalizeUcanCapabilities(options.capabilities);
     if (!normalizedCapabilities.length) {
@@ -1228,7 +1389,7 @@ async function createDelegationUcan(options) {
     if (!normalizedCapabilities.length) {
         throw new Error('Missing UCAN capabilities');
     }
-    const exp = normalizeExpiry(undefined, options.expiresInMs ?? DEFAULT_UCAN_TTL);
+    const exp = normalizeExpiry(undefined, options.expiresInMs ?? DEFAULT_UCAN_TOKEN_TTL_MS);
     const payload = {
         iss: issuer.did,
         aud: options.audience,
@@ -1250,7 +1411,7 @@ async function createInvocationUcan(options) {
     if (!normalizedCapabilities.length) {
         throw new Error('Missing UCAN capabilities');
     }
-    const exp = normalizeExpiry(undefined, options.expiresInMs ?? DEFAULT_UCAN_TTL);
+    const exp = normalizeExpiry(undefined, options.expiresInMs ?? DEFAULT_UCAN_TOKEN_TTL_MS);
     const payload = {
         iss: issuer.did,
         aud: options.audience,
@@ -1261,30 +1422,84 @@ async function createInvocationUcan(options) {
     };
     return await signUcanPayload(payload, issuer);
 }
+async function getOrCreateInvocationUcan(options) {
+    if (options.ucan &&
+        isUcanTokenFresh(options.ucan, {
+            nowMs: options.nowMs,
+            skewMs: options.skewMs,
+        })) {
+        return options.ucan;
+    }
+    return await createInvocationUcan({
+        issuer: options.issuer,
+        sessionId: options.sessionId,
+        provider: options.provider,
+        audience: options.audience,
+        capabilities: options.capabilities,
+        expiresInMs: options.expiresInMs,
+        notBeforeMs: options.notBeforeMs,
+        proofs: options.proofs,
+    });
+}
 async function authUcanFetch(input, init = {}, options = {}) {
     const fetcher = options.fetcher || fetch;
-    let token = options.ucan;
-    if (!token) {
-        if (!options.audience || !options.capabilities) {
+    const audience = options.audience;
+    const capabilities = options.capabilities;
+    const canRefresh = Boolean(audience && capabilities);
+    const canRetry = canRefresh && isReplayableRequestBody(init.body);
+    let token = options.ucan || '';
+    if (!token || (canRefresh && !isUcanTokenFresh(token, { skewMs: options.skewMs }))) {
+        if (!audience || !capabilities) {
             throw new Error('Missing UCAN audience or capabilities');
         }
-        token = await createInvocationUcan({
+        token = await getOrCreateInvocationUcan({
+            ucan: options.ucan,
             issuer: options.issuer,
             sessionId: options.sessionId,
             provider: options.provider,
-            audience: options.audience,
-            capabilities: options.capabilities,
+            audience,
+            capabilities,
             expiresInMs: options.expiresInMs,
             notBeforeMs: options.notBeforeMs,
             proofs: options.proofs,
+            skewMs: options.skewMs,
         });
     }
-    const headers = new Headers(init.headers || {});
-    headers.set('Authorization', `Bearer ${token}`);
-    return fetcher(input, {
+    const makeHeaders = (bearer) => {
+        const headers = new Headers(init.headers || {});
+        headers.set('Authorization', `Bearer ${bearer}`);
+        return headers;
+    };
+    let response = await fetcher(input, {
         ...init,
-        headers,
+        headers: makeHeaders(token),
+    });
+    if (!canRetry || response.ok) {
+        return response;
+    }
+    const payload = await parseResponseJsonBody(response.clone()).catch(() => null);
+    const errorInfo = classifyUcanAuthError(payload || response.statusText || response);
+    if (!shouldRetryUcanFetch(response, errorInfo)) {
+        return response;
+    }
+    if (!audience || !capabilities) {
+        return response;
+    }
+    const refreshedToken = await createInvocationUcan({
+        issuer: options.issuer,
+        sessionId: options.sessionId,
+        provider: options.provider,
+        audience,
+        capabilities,
+        expiresInMs: options.expiresInMs,
+        notBeforeMs: options.notBeforeMs,
+        proofs: options.proofs,
     });
+    response = await fetcher(input, {
+        ...init,
+        headers: makeHeaders(refreshedToken),
+    });
+    return response;
 }
 
 const DEFAULT_BASE_URL = '/api/v1/public/auth/central';
@@ -1879,7 +2094,6 @@ function createWebDavClient(options) {
 }
 
 const tokenCache = new Map();
-const TOKEN_SKEW_MS = 5000;
 const DEFAULT_APP_ACTION = 'write';
 const LOOPBACK_HOST_ALIASES = new Set([
     'localhost',
@@ -2021,64 +2235,19 @@ function resolveInvocationCaps(options, fallbackCaps) {
     const caps = options.invocationCapabilities || fallbackCaps;
     return ensureAppCapability(caps, options);
 }
-function isTokenValid(entry, nowMs) {
-    if (!entry.exp)
-        return false;
-    if (entry.nbf && nowMs < entry.nbf)
-        return false;
-    return entry.exp - TOKEN_SKEW_MS > nowMs;
-}
-function decodeBase64Url(input) {
-    if (!input)
-        return null;
-    const base64 = input.replace(/-/g, '+').replace(/_/g, '/');
-    const padded = base64.padEnd(Math.ceil(base64.length / 4) * 4, '=');
-    try {
-        if (typeof atob === 'function') {
-            return atob(padded);
-        }
-    }
-    catch {
-        // ignore
-    }
-    try {
-        const nodeBuffer = globalThis.Buffer;
-        if (nodeBuffer) {
-            return nodeBuffer.from(padded, 'base64').toString('utf8');
-        }
-    }
-    catch {
-        return null;
-    }
-    return null;
-}
-function decodeUcanPayload(token) {
-    const parts = token.split('.');
-    if (parts.length < 2)
-        return null;
-    const decoded = decodeBase64Url(parts[1]);
-    if (!decoded)
-        return null;
-    try {
-        return JSON.parse(decoded);
-    }
-    catch {
-        return null;
-    }
-}
 async function getCachedInvocationToken(options) {
     const cacheKey = buildTokenCacheKey(options.issuer, options.audience, options.capabilities);
     const cached = tokenCache.get(cacheKey);
     const nowMs = Date.now();
-    if (cached && isTokenValid(cached, nowMs)) {
-        return cached.token;
-    }
-    const token = await createInvocationUcan({
+    const token = await getOrCreateInvocationUcan({
+        ucan: cached?.token,
         issuer: options.issuer,
         audience: options.audience,
         capabilities: options.capabilities,
         proofs: options.proofs,
         expiresInMs: options.expiresInMs,
+        skewMs: options.skewMs,
+        nowMs,
         notBeforeMs: options.notBeforeMs,
     });
     const payload = decodeUcanPayload(token);
@@ -2129,6 +2298,7 @@ async function initWebDavStorage(options) {
         capabilities: invocationCaps,
         proofs: [root],
         expiresInMs: options.invocationExpiresInMs,
+        skewMs: options.invocationSkewMs,
         notBeforeMs: options.notBeforeMs,
     });
     const client = createWebDavClient({
@@ -2185,5 +2355,5 @@ async function initDappSession(options) {
     return result;
 }
 
-export { WebDavClient, authCentralUcanFetch, authFetch, authUcanFetch, classifyWalletError, clearAccessToken, clearCentralSessionToken, clearUcanSession, createAndIssueCentralUcan, createCentralSession, createDelegationUcan, createInvocationUcan, createRootUcan, createUcanSession, createWebDavClient, deriveAppIdFromHost, deriveAppIdFromLocation, focusPendingApproval, getAccessToken, getAccounts, getBalance, getCapabilityAction, getCapabilityResource, getCentralIssuerInfo, getCentralSessionToken, getChainId, getOrCreateUcanRoot, getPreferredAccount, getProvider, getStoredUcanRoot, getUcanSession, getWalletErrorCode, getWalletErrorMessage, initDappSession, initWebDavStorage, isUserRejectedWalletAction, isWalletReconnectError, isYeYingProvider, issueCentralUcan, loginWithChallenge, logout, normalizeAppHostnameForAppId, normalizeUcanCapabilities, normalizeUcanCapability, onAccountsChanged, onChainChanged, refreshAccessToken, requestAccounts, requireProvider, setAccessToken, setCentralSessionToken, signMessage, storeUcanRoot, watchAccounts, watchProvider };
+export { DEFAULT_UCAN_SESSION_TTL_MS, DEFAULT_UCAN_TOKEN_SKEW_MS, DEFAULT_UCAN_TOKEN_TTL_MS, WebDavClient, authCentralUcanFetch, authFetch, authUcanFetch, classifyUcanAuthError, classifyWalletError, clearAccessToken, clearCentralSessionToken, clearUcanSession, createAndIssueCentralUcan, createCentralSession, createDelegationUcan, createInvocationUcan, createRootUcan, createUcanSession, createWebDavClient, decodeUcanPayload, deriveAppIdFromHost, deriveAppIdFromLocation, focusPendingApproval, getAccessToken, getAccounts, getBalance, getCapabilityAction, getCapabilityResource, getCentralIssuerInfo, getCentralSessionToken, getChainId, getOrCreateInvocationUcan, getOrCreateUcanRoot, getPreferredAccount, getProvider, getStoredUcanRoot, getUcanSession, getUcanTokenTiming, getWalletErrorCode, getWalletErrorMessage, initDappSession, initWebDavStorage, isUcanTokenFresh, isUserRejectedWalletAction, isWalletReconnectError, isYeYingProvider, issueCentralUcan, loginWithChallenge, logout, normalizeAppHostnameForAppId, normalizeUcanCapabilities, normalizeUcanCapability, normalizeUcanExpiry, onAccountsChanged, onChainChanged, refreshAccessToken, requestAccounts, requireProvider, setAccessToken, setCentralSessionToken, signMessage, storeUcanRoot, watchAccounts, watchProvider };
 //# sourceMappingURL=web3-bs.esm.js.map