@enbox/browser 0.3.53 → 0.3.55

package/src/browser-connect-handler.ts

@@ -7,8 +7,9 @@
  * @module
  */
 
-import type { ConnectPermissionRequest } from '@enbox/connect';
+import type { PortableDid } from '@enbox/dids';
 import type { ConnectHandler, ConnectResult } from '@enbox/auth';
+import type { ConnectPermissionRequest, ConnectRequestType } from '@enbox/connect';
 
 import { runConnectModal } from './ui/connect-modal.js';
 
@@ -175,6 +176,8 @@ export function BrowserConnectHandler(
   return {
     async requestAccess(params: {
       permissionRequests: ConnectPermissionRequest[];
+      delegatePortableDid?: PortableDid;
+      requestType?: ConnectRequestType;
     }): Promise<ConnectResult | undefined> {
       return runConnectModal({
         wallets,
@@ -182,12 +185,14 @@ export function BrowserConnectHandler(
         preferredMethod,
         rememberChoice,
         appName,
-        appIcon            : appIcon ?? `${window.location.origin}/favicon.ico`,
+        appIcon             : appIcon ?? `${window.location.origin}/favicon.ico`,
         connectServerUrl,
         relayWalletPath,
         timeout,
         theme,
-        permissionRequests : params.permissionRequests,
+        mode                : params.requestType,
+        delegatePortableDid : params.delegatePortableDid,
+        permissionRequests  : params.permissionRequests,
       });
     },
   };

package/src/index.ts

@@ -49,6 +49,11 @@ export type {
 export {
   AuthManager,
   AuthSession,
+  SESSION_EXPIRED_ERROR_CODE,
+  SESSION_REVOKED_ERROR_CODE,
+  computeConnectionStatus,
+  isSessionExpiredError,
+  isSessionInvalidError,
   normalizeProtocolRequests,
   WalletConnect,
 } from '@enbox/auth/browser';
@@ -58,16 +63,23 @@ export type {
   AuthEventHandler,
   AuthManagerOptions,
   AuthState,
+  ComputeConnectionStatusOptions,
+  ConnectionMonitorOptions,
+  ConnectionState,
+  ConnectionStatus,
+  ConnectionStatusGrant,
   ConnectHandler,
   ConnectOptions,
   ConnectResult,
   DisconnectOptions,
+  GetConnectionStatusOptions,
   HandlerConnectOptions,
   ImportFromPortableOptions,
   VaultConnectOptions,
   Permission,
   PortableIdentity,
   ProtocolRequest,
+  RefreshOptions,
   RegistrationOptions,
   StorageAdapter,
   SyncOption,
@@ -80,7 +92,7 @@ export type {
 // transports: opening/sealing envelopes and the deny token.
 
 export { CONNECT_DENIED_TOKEN, ConnectProvider } from '@enbox/connect';
-export type { ConnectApproval, ConnectPermissionRequest, ConnectRequest } from '@enbox/connect';
+export type { ConnectApproval, ConnectPermissionRequest, ConnectRequest, ConnectRequestType } from '@enbox/connect';
 
 // ─── Browser-specific exports ───────────────────────────────────
 //

package/src/relay-connect-runner.ts

@@ -20,10 +20,12 @@
  */
 
 import type { Jwk } from '@enbox/crypto';
+import type { PortableDid } from '@enbox/dids';
 import type {
   ConnectClientMetadata,
   ConnectPermissionRequest,
   ConnectRequest,
+  ConnectRequestType,
   ConnectResult,
   WalletUriHandoff,
 } from '@enbox/connect';
@@ -35,6 +37,7 @@ import {
   openResponse,
   randomToken,
   RelayClientTransport,
+  resolveDelegatePortableDid,
   sealRequest,
 } from '@enbox/connect';
 
@@ -69,6 +72,12 @@ export interface RelayConnectOptions {
   /** DWN protocols and permission scopes being requested. */
   permissionRequests: ConnectPermissionRequest[];
 
+  /** Existing delegate credentials reused by a refresh request. */
+  delegatePortableDid?: PortableDid;
+
+  /** User-facing request purpose. Absent means a normal connect. */
+  requestType?: ConnectRequestType;
+
   /** Total milliseconds to poll the relay for a wallet response. */
   timeoutMs?: number;
 
@@ -107,6 +116,7 @@ export interface RelayConnectOptions {
     timeoutMs?: number;
     pollIntervalMs?: number;
     onClaimed?: () => void;
+    signal?: AbortSignal;
   }) => Pick<RelayClientTransport, 'requestProfile' | 'deliverRequest' | 'awaitResponse' | 'requiresPin'>
     & Partial<Pick<RelayClientTransport, 'confirmComplete'>>;
 }
@@ -147,18 +157,24 @@ export function visibilityAwareSleep(ms: number): Promise<void> {
  * delegated credentials, or `undefined` when the user denied in the wallet.
  */
 export async function runRelayConnect(options: RelayConnectOptions): Promise<ConnectResult | undefined> {
+  if (options.requestType === 'refresh' && options.delegatePortableDid === undefined) {
+    throw new Error('Connect: refresh requests require an existing `delegatePortableDid`.');
+  }
+
   const createTransport = options.createTransport
     ?? ((transportOptions): RelayClientTransport => new RelayClientTransport({
       ...transportOptions,
       sleep: visibilityAwareSleep,
     }));
 
+  const cancellationController = options.cancelled === undefined ? undefined : new AbortController();
   const transport = createTransport({
     connectServerUrl : options.connectServerUrl,
     walletUri        : options.walletUri,
     timeoutMs        : options.timeoutMs,
     pollIntervalMs   : options.pollIntervalMs,
     onClaimed        : options.onClaimed,
+    signal           : cancellationController?.signal,
   });
 
   // Ephemeral client DID for request signing and response addressing, and a
@@ -179,6 +195,8 @@ export async function runRelayConnect(options: RelayConnectOptions): Promise<Con
     appIcon             : options.appIcon,
     clientMetadata      : options.clientMetadata,
     permissionRequests  : options.permissionRequests,
+    delegateDid         : options.delegatePortableDid?.uri,
+    requestType         : options.requestType,
     supportedDidMethods : ['did:dht', 'did:jwk'],
     nonce,
     state,
@@ -197,7 +215,13 @@ export async function runRelayConnect(options: RelayConnectOptions): Promise<Con
     ? transport.awaitResponse()
     : Promise.race([transport.awaitResponse(), options.cancelled]);
 
-  const responseCiphertext = await race;
+  let responseCiphertext: string;
+  try {
+    responseCiphertext = await race;
+  } catch (error) {
+    cancellationController?.abort();
+    throw error;
+  }
   if (responseCiphertext === CONNECT_DENIED_TOKEN) {
     return undefined;
   }
@@ -220,9 +244,10 @@ export async function runRelayConnect(options: RelayConnectOptions): Promise<Con
         pin,
       });
 
-      if (response.delegatePortableDid === undefined) {
-        throw new Error('Connect: wallet response omitted `delegatePortableDid`.');
-      }
+      const delegatePortableDid = resolveDelegatePortableDid({
+        localDelegatePortableDid: options.delegatePortableDid,
+        response,
+      });
 
       // Best-effort completion signal so the wallet can flip its pairing
       // screen to a confirmed "connected" state instead of leaving the user
@@ -230,10 +255,10 @@ export async function runRelayConnect(options: RelayConnectOptions): Promise<Con
       void transport.confirmComplete?.().catch((): undefined => undefined);
 
       return {
-        delegatePortableDid : response.delegatePortableDid,
-        delegateGrants      : response.delegateGrants,
-        connectedDid        : response.providerDid,
-        sessionRevocations  : response.sessionRevocations,
+        delegatePortableDid,
+        delegateGrants     : response.delegateGrants,
+        connectedDid       : response.providerDid,
+        sessionRevocations : response.sessionRevocations,
       };
     } catch (error) {
       const failure = error instanceof Error ? error : new Error(String(error));

package/src/ui/connect-modal.ts

@@ -37,8 +37,9 @@
  * @module
  */
 
+import type { PortableDid } from '@enbox/dids';
 import type { WalletOption } from '../browser-connect-handler.js';
-import type { ConnectPermissionRequest, ConnectResult, WalletUriHandoff } from '@enbox/connect';
+import type { ConnectPermissionRequest, ConnectRequestType, ConnectResult, WalletUriHandoff } from '@enbox/connect';
 
 import { ConnectClient } from '@enbox/connect';
 
@@ -157,6 +158,12 @@ export interface ConnectModalOptions {
    */
   walletUrl?: string;
 
+  /** User-facing mode. Absent means a normal connect. */
+  mode?: ConnectRequestType;
+
+  /** Existing delegate credentials reused by a refresh request. */
+  delegatePortableDid?: PortableDid;
+
   /** Preferred method on open; overrides the remembered choice. */
   preferredMethod?: ConnectMethod;
 
@@ -215,6 +222,8 @@ export interface ConnectModalDeps {
     appName: string;
     appIcon?: string;
     timeoutMs?: number;
+    delegatePortableDid?: PortableDid;
+    requestType?: ConnectRequestType;
   }) => Promise<ConnectResult | undefined>;
 
   /** Resolves a wallet origin to its relay `connectServerUrl` (or undefined). */
@@ -246,6 +255,8 @@ async function runPopupConnect(options: {
   appName: string;
   appIcon?: string;
   timeoutMs?: number;
+  delegatePortableDid?: PortableDid;
+  requestType?: ConnectRequestType;
 }): Promise<ConnectResult | undefined> {
   // The transport constructor calls `window.open` synchronously — callers
   // must invoke this inside the user-gesture call stack.
@@ -256,10 +267,12 @@ async function runPopupConnect(options: {
   const client = new ConnectClient({ transport });
 
   return await client.connect({
-    appName            : options.appName,
-    appIcon            : options.appIcon,
-    clientMetadata     : collectBrowserClientMetadata(),
-    permissionRequests : options.permissionRequests,
+    appName             : options.appName,
+    appIcon             : options.appIcon,
+    clientMetadata      : collectBrowserClientMetadata(),
+    permissionRequests  : options.permissionRequests,
+    delegatePortableDid : options.delegatePortableDid,
+    requestType         : options.requestType,
   });
 }
 
@@ -295,7 +308,7 @@ function readLastChoice(storage: ConnectModalDeps['storage']): LastChoice | unde
       return undefined;
     }
     const parsed = JSON.parse(raw) as Partial<LastChoice>;
-    if ((parsed.method === 'phone' || parsed.method === 'browser') && typeof parsed.walletUrl === 'string') {
+    if ((parsed.method === 'phone' || parsed.method === 'browser') && isValidRememberedWalletUrl(parsed.walletUrl)) {
       return { method: parsed.method, walletUrl: parsed.walletUrl };
     }
   } catch { /* unreadable storage — behave as first visit */ }
@@ -345,6 +358,9 @@ export function runConnectModal(options: ConnectModalOptions): Promise<ConnectRe
   if (typeof window === 'undefined' || typeof document === 'undefined') {
     throw new Error('[@enbox/browser] The connect modal is only available in browser environments.');
   }
+  if (options.mode === 'refresh' && options.delegatePortableDid === undefined) {
+    throw new Error('Connect: refresh requests require an existing `delegatePortableDid`.');
+  }
 
   const deps: ConnectModalDeps = { ...defaultDeps(), ...options.deps };
   const wallets = dedupeWalletsByUrl(options.wallets ?? []);
@@ -352,13 +368,18 @@ export function runConnectModal(options: ConnectModalOptions): Promise<ConnectRe
   const appName = options.appName ?? window.location.host;
   const relayWalletPath = options.relayWalletPath ?? '/connect/app';
   const isMobile = deps.isMobile();
+  const refreshing = options.mode === 'refresh';
 
   const lastChoice = rememberChoice ? readLastChoice(deps.storage) : undefined;
 
   // Wallet resolution order: explicit option → remembered → catalog head.
-  const lockedWallet = options.walletUrl !== undefined;
+  const rememberedWalletUrl = lastChoice !== undefined
+    && (refreshing || walletInCatalog(wallets, lastChoice.walletUrl))
+    ? lastChoice.walletUrl
+    : undefined;
+  const lockedWallet = options.walletUrl !== undefined || (refreshing && rememberedWalletUrl !== undefined);
   let walletUrl = options.walletUrl
-    ?? (lastChoice !== undefined && (lockedWallet || walletInCatalog(wallets, lastChoice.walletUrl)) ? lastChoice.walletUrl : undefined)
+    ?? rememberedWalletUrl
     ?? wallets[0]?.url;
 
   // Method resolution order: explicit option → remembered → phone.
@@ -380,7 +401,8 @@ export function runConnectModal(options: ConnectModalOptions): Promise<ConnectRe
     modal.className = 'modal';
     modal.setAttribute('role', 'dialog');
     modal.setAttribute('aria-modal', 'true');
-    modal.setAttribute('aria-label', `Connect to ${appName}`);
+    const title = refreshing ? `Reconnect to ${appName}` : `Connect to ${appName}`;
+    modal.setAttribute('aria-label', title);
 
     // ── Theme ──────────────────────────────────────────────────
     // System light/dark is pure CSS (`prefers-color-scheme`), so it tracks
@@ -489,7 +511,7 @@ export function runConnectModal(options: ConnectModalOptions): Promise<ConnectRe
     const cancelModal = (): void => settle(() => reject(new Error('[@enbox/browser] Connect cancelled.')));
 
     // ── Zones ──────────────────────────────────────────────────
-    modal.appendChild(buildHeader(appName, options.appIcon, cancelModal));
+    modal.appendChild(buildHeader(title, options.appIcon, cancelModal));
 
     const stage = document.createElement('div');
     stage.className = 'stage';
@@ -839,14 +861,16 @@ export function runConnectModal(options: ConnectModalOptions): Promise<ConnectRe
       try {
         const result = await deps.runRelay({
           connectServerUrl,
-          walletUri          : new URL(relayWalletPath, origin).toString(),
+          walletUri           : new URL(relayWalletPath, origin).toString(),
           appName,
-          appIcon            : options.appIcon,
-          clientMetadata     : collectBrowserClientMetadata(),
-          permissionRequests : options.permissionRequests,
-          timeoutMs          : options.timeout,
-          cancelled          : session.cancelled,
-          onWalletUriReady   : (handoff): void => {
+          appIcon             : options.appIcon,
+          clientMetadata      : collectBrowserClientMetadata(),
+          permissionRequests  : options.permissionRequests,
+          delegatePortableDid : options.delegatePortableDid,
+          requestType         : options.mode,
+          timeoutMs           : options.timeout,
+          cancelled           : session.cancelled,
+          onWalletUriReady    : (handoff): void => {
             if (session.active && !settled) {
               renderQr(handoff);
               scheduleRemint(handoff.expiresIn);
@@ -907,10 +931,12 @@ export function runConnectModal(options: ConnectModalOptions): Promise<ConnectRe
       try {
         deps.runPopup({
           walletUrl,
-          permissionRequests : options.permissionRequests,
+          permissionRequests  : options.permissionRequests,
           appName,
-          appIcon            : options.appIcon,
-          timeoutMs          : options.timeout,
+          appIcon             : options.appIcon,
+          timeoutMs           : options.timeout,
+          delegatePortableDid : options.delegatePortableDid,
+          requestType         : options.mode,
         })
           .then((result) => {
             if (settled) { return; }
@@ -1226,6 +1252,19 @@ function walletInCatalog(wallets: WalletOption[], url: string): boolean {
   return wallets.some((wallet) => wallet.url === url);
 }
 
+function isValidRememberedWalletUrl(value: unknown): value is string {
+  if (typeof value !== 'string' || value.trim() === '') {
+    return false;
+  }
+
+  try {
+    const url = new URL(value);
+    return url.protocol === 'http:' || url.protocol === 'https:';
+  } catch {
+    return false;
+  }
+}
+
 /** Drops catalog entries that repeat an earlier wallet's URL. */
 function dedupeWalletsByUrl(wallets: WalletOption[]): WalletOption[] {
   return wallets.filter((wallet, index) => wallets.findIndex((candidate) => candidate.url === wallet.url) === index);
@@ -1268,7 +1307,7 @@ function stageLinkButton(label: string, onClick: () => void): HTMLButtonElement
   return button;
 }
 
-function buildHeader(appName: string, appIcon: string | undefined, onCancel: () => void): HTMLDivElement {
+function buildHeader(titleText: string, appIcon: string | undefined, onCancel: () => void): HTMLDivElement {
   const header = document.createElement('div');
   header.className = 'header';
 
@@ -1287,7 +1326,7 @@ function buildHeader(appName: string, appIcon: string | undefined, onCancel: ()
   }
 
   const title = document.createElement('h2');
-  title.textContent = `Connect to ${appName}`;
+  title.textContent = titleText;
   identity.appendChild(title);
 
   const closeBtn = document.createElement('button');