@enbox/browser 0.1.3 → 0.1.4

package/dist/types/dweb-connect-client.d.ts

@@ -0,0 +1,63 @@
+/**
+ * DWeb Connect client — initiates the popup/postMessage connect flow.
+ *
+ * This is the dapp-side counterpart to the wallet's `/dweb-connect` page.
+ * The wallet is opened as a popup window, and communication happens via
+ * `window.postMessage`. No relay server, QR codes, or PINs are needed.
+ *
+ * @module
+ */
+import type { ConnectResult } from '@enbox/auth';
+import type { ConnectPermissionRequest } from '@enbox/agent';
+/** Options for initiating a DWeb Connect flow via popup. */
+export interface DWebConnectClientOptions {
+    /** Base URL of the wallet app (e.g. "https://wallet.enbox.org"). */
+    walletUrl: string;
+    /** The DID to pre-select in the wallet's identity picker. */
+    did?: string;
+    /**
+     * Protocol permission requests to send to the wallet.
+     * Each entry contains a `protocolDefinition` and `permissionScopes`.
+     */
+    permissionRequests: ConnectPermissionRequest[];
+    /**
+     * Timeout in milliseconds. The popup is closed and an error thrown
+     * if the wallet doesn't respond within this time.
+     * @default 300_000 (5 minutes)
+     */
+    timeout?: number;
+}
+/**
+ * Open a wallet popup and run the DWeb Connect postMessage flow.
+ *
+ * Protocol:
+ * 1. Dapp opens `${walletUrl}/dweb-connect` as a popup.
+ * 2. Wallet sends `{ type: 'dweb-connect-loaded' }` when ready.
+ * 3. Dapp sends `{ type: 'dweb-connect-authorization-request', did, permissions }`.
+ * 4. Wallet shows consent UI, then sends back
+ *    `{ type: 'dweb-connect-authorization-response', delegateDid, grants }`.
+ * 5. Popup closes.
+ *
+ * @returns The delegate credentials, or `undefined` if the user denied.
+ * @throws If the popup is blocked, times out, or the wallet returns an error.
+ */
+declare function initClient(options: DWebConnectClientOptions): Promise<ConnectResult | undefined>;
+/**
+ * Probe whether a wallet supports a specific DID via a hidden iframe.
+ *
+ * Sends a `dweb-connect-support-request` message to the wallet and
+ * waits for a `dweb-connect-support-response`. Useful for checking
+ * multiple wallet URLs to find the one that manages a given DID.
+ *
+ * @param walletUrl - Base URL of the wallet to probe.
+ * @param did - The DID to check.
+ * @param timeout - Probe timeout in ms. Default: 5_000 (5 seconds).
+ * @returns `true` if the wallet manages the DID, `false` otherwise.
+ */
+declare function probeWalletSupport(walletUrl: string, did: string, timeout?: number): Promise<boolean>;
+export declare const DWebConnect: {
+    initClient: typeof initClient;
+    probeWalletSupport: typeof probeWalletSupport;
+};
+export {};
+//# sourceMappingURL=dweb-connect-client.d.ts.map

package/dist/types/dweb-connect-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dweb-connect-client.d.ts","sourceRoot":"","sources":["../../src/dweb-connect-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD,OAAO,KAAK,EAAE,wBAAwB,EAAqC,MAAM,cAAc,CAAC;AAEhG,4DAA4D;AAC5D,MAAM,WAAW,wBAAwB;IACvC,oEAAoE;IACpE,SAAS,EAAE,MAAM,CAAC;IAElB,6DAA6D;IAC7D,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb;;;OAGG;IACH,kBAAkB,EAAE,wBAAwB,EAAE,CAAC;IAE/C;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;;;GAaG;AACH,iBAAe,UAAU,CAAC,OAAO,EAAE,wBAAwB,GAAG,OAAO,CAAC,aAAa,GAAG,SAAS,CAAC,CAgG/F;AAED;;;;;;;;;;;GAWG;AACH,iBAAe,kBAAkB,CAC/B,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,MAAM,EACX,OAAO,SAAQ,GACd,OAAO,CAAC,OAAO,CAAC,CA+ClB;AAED,eAAO,MAAM,WAAW;;;CAAqC,CAAC"}

package/dist/types/index.d.ts

@@ -1,2 +1,6 @@
 export * from './web-features.js';
+export { BrowserConnectHandler, DEFAULT_WALLETS } from './browser-connect-handler.js';
+export type { BrowserConnectHandlerOptions, WalletOption } from './browser-connect-handler.js';
+export { DWebConnect } from './dweb-connect-client.js';
+export type { DWebConnectClientOptions } from './dweb-connect-client.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/types/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAClC,OAAO,EAAE,qBAAqB,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AACtF,YAAY,EAAE,4BAA4B,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AAC/F,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AACvD,YAAY,EAAE,wBAAwB,EAAE,MAAM,0BAA0B,CAAC"}

package/dist/types/ui/wallet-selector.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Wallet selector modal — a self-contained, framework-agnostic UI component.
+ *
+ * Injected into the DOM as a Shadow DOM element to prevent style conflicts.
+ * Inspired by WalletConnect's Web3Modal pattern.
+ *
+ * @module
+ */
+import type { WalletOption } from '../browser-connect-handler.js';
+/** Shows the wallet selector modal and resolves with the chosen wallet URL. */
+export declare function showWalletSelector(wallets: WalletOption[]): Promise<string>;
+//# sourceMappingURL=wallet-selector.d.ts.map

package/dist/types/ui/wallet-selector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wallet-selector.d.ts","sourceRoot":"","sources":["../../../src/ui/wallet-selector.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAElE,+EAA+E;AAC/E,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,YAAY,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAmK3E"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enbox/browser",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Enbox tools and features to use in the browser",
   "type": "module",
   "main": "./dist/esm/index.js",
@@ -55,6 +55,8 @@
     "access": "public"
   },
   "dependencies": {
+    "@enbox/agent": "0.5.1",
+    "@enbox/auth": "0.6.1",
     "@enbox/dids": "0.1.0"
   },
   "devDependencies": {

package/src/browser-connect-handler.ts

@@ -0,0 +1,103 @@
+/**
+ * Browser connect handler for `@enbox/auth`.
+ *
+ * Implements the {@link ConnectHandler} interface using browser-native
+ * DWeb Connect (popup + postMessage) with a wallet selector modal.
+ *
+ * @module
+ */
+
+import type { ConnectPermissionRequest } from '@enbox/agent';
+import type { ConnectHandler, ConnectResult } from '@enbox/auth';
+
+import { DWebConnect } from './dweb-connect-client.js';
+import { showWalletSelector } from './ui/wallet-selector.js';
+
+/** A wallet entry shown in the wallet selector modal. */
+export interface WalletOption {
+  /** Display name (e.g. "Enbox Wallet"). */
+  name: string;
+
+  /** Base URL of the wallet app (e.g. "https://wallet.enbox.org"). */
+  url: string;
+
+  /** Optional icon URL. If omitted, the wallet's favicon is used. */
+  icon?: string;
+}
+
+/** Default wallets shown in the selector when no overrides are provided. */
+export const DEFAULT_WALLETS: WalletOption[] = [
+  { name: 'Enbox Wallet', url: 'https://wallet.enbox.org' },
+];
+
+/** Options for creating a BrowserConnectHandler. */
+export interface BrowserConnectHandlerOptions {
+  /**
+   * Known wallets shown in the wallet selector modal.
+   * If omitted, {@link DEFAULT_WALLETS} is used.
+   */
+  wallets?: WalletOption[];
+
+  /**
+   * Explicit wallet URL. If provided, the wallet selector is skipped
+   * and this URL is used directly.
+   */
+  walletUrl?: string;
+
+  /**
+   * Timeout in milliseconds for the wallet popup flow.
+   * @default 300_000 (5 minutes)
+   */
+  timeout?: number;
+}
+
+/**
+ * Create a browser-native connect handler using DWeb Connect
+ * (popup + postMessage).
+ *
+ * This handler:
+ * 1. Shows a wallet selector modal (or uses a provided walletUrl).
+ * 2. Opens the selected wallet as a popup window.
+ * 3. Runs the DWeb Connect postMessage protocol.
+ * 4. Returns the delegate credentials on success.
+ *
+ * @example
+ * ```ts
+ * import { AuthManager } from '@enbox/auth';
+ * import { BrowserConnectHandler } from '@enbox/browser';
+ *
+ * const auth = await AuthManager.create({
+ *   connectHandler: BrowserConnectHandler(),
+ * });
+ *
+ * const session = await auth.connect({ protocols: [NotesProtocol] });
+ * ```
+ */
+export function BrowserConnectHandler(
+  options: BrowserConnectHandlerOptions = {},
+): ConnectHandler {
+  const {
+    wallets = DEFAULT_WALLETS,
+    walletUrl: fixedWalletUrl,
+    timeout,
+  } = options;
+
+  return {
+    async requestAccess(params: {
+      permissionRequests: ConnectPermissionRequest[];
+    }): Promise<ConnectResult | undefined> {
+      // 1. Determine wallet URL.
+      let walletUrl = fixedWalletUrl;
+      if (!walletUrl) {
+        walletUrl = await showWalletSelector(wallets);
+      }
+
+      // 2. Run the DWeb Connect popup flow.
+      return DWebConnect.initClient({
+        walletUrl,
+        permissionRequests: params.permissionRequests,
+        timeout,
+      });
+    },
+  };
+}

package/src/dweb-connect-client.ts

@@ -0,0 +1,214 @@
+/**
+ * DWeb Connect client — initiates the popup/postMessage connect flow.
+ *
+ * This is the dapp-side counterpart to the wallet's `/dweb-connect` page.
+ * The wallet is opened as a popup window, and communication happens via
+ * `window.postMessage`. No relay server, QR codes, or PINs are needed.
+ *
+ * @module
+ */
+
+import type { ConnectResult } from '@enbox/auth';
+import type { PortableDid } from '@enbox/dids';
+import type { ConnectPermissionRequest, DwnDataEncodedRecordsWriteMessage } from '@enbox/agent';
+
+/** Options for initiating a DWeb Connect flow via popup. */
+export interface DWebConnectClientOptions {
+  /** Base URL of the wallet app (e.g. "https://wallet.enbox.org"). */
+  walletUrl: string;
+
+  /** The DID to pre-select in the wallet's identity picker. */
+  did?: string;
+
+  /**
+   * Protocol permission requests to send to the wallet.
+   * Each entry contains a `protocolDefinition` and `permissionScopes`.
+   */
+  permissionRequests: ConnectPermissionRequest[];
+
+  /**
+   * Timeout in milliseconds. The popup is closed and an error thrown
+   * if the wallet doesn't respond within this time.
+   * @default 300_000 (5 minutes)
+   */
+  timeout?: number;
+}
+
+/**
+ * Open a wallet popup and run the DWeb Connect postMessage flow.
+ *
+ * Protocol:
+ * 1. Dapp opens `${walletUrl}/dweb-connect` as a popup.
+ * 2. Wallet sends `{ type: 'dweb-connect-loaded' }` when ready.
+ * 3. Dapp sends `{ type: 'dweb-connect-authorization-request', did, permissions }`.
+ * 4. Wallet shows consent UI, then sends back
+ *    `{ type: 'dweb-connect-authorization-response', delegateDid, grants }`.
+ * 5. Popup closes.
+ *
+ * @returns The delegate credentials, or `undefined` if the user denied.
+ * @throws If the popup is blocked, times out, or the wallet returns an error.
+ */
+async function initClient(options: DWebConnectClientOptions): Promise<ConnectResult | undefined> {
+  const {
+    walletUrl,
+    did,
+    permissionRequests,
+    timeout = 300_000,
+  } = options;
+
+  if (typeof window === 'undefined') {
+    throw new Error(
+      '[@enbox/auth] DWeb Connect is only available in browser environments.'
+    );
+  }
+
+  // Open the wallet's DWeb Connect page as a popup.
+  const popupUrl = new URL('/dweb-connect', walletUrl).toString();
+  const popup = window.open(
+    popupUrl,
+    'enbox-dweb-connect',
+    'width=500,height=700,menubar=no,toolbar=no,location=no,status=no',
+  );
+
+  if (!popup) {
+    throw new Error(
+      '[@enbox/auth] Popup blocked. Allow popups for this site to connect to a wallet.'
+    );
+  }
+
+  return new Promise<ConnectResult | undefined>((resolve, reject) => {
+    let settled = false;
+
+    const cleanup = (): void => {
+      settled = true;
+      clearTimeout(timeoutId);
+      window.removeEventListener('message', onMessage);
+    };
+
+    // Set up timeout.
+    const timeoutId = setTimeout(() => {
+      if (!settled) {
+        cleanup();
+        try { popup.close(); } catch { /* best effort */ }
+        reject(new Error(
+          '[@enbox/auth] DWeb Connect timed out waiting for wallet response.'
+        ));
+      }
+    }, timeout);
+
+    // Monitor popup closed without response (user closed the window).
+    const pollClosed = setInterval(() => {
+      if (popup.closed && !settled) {
+        clearInterval(pollClosed);
+        cleanup();
+        resolve(undefined);
+      }
+    }, 500);
+
+    const onMessage = (event: MessageEvent): void => {
+      // Validate origin matches the wallet URL.
+      const walletOrigin = new URL(walletUrl).origin;
+      if (event.origin !== walletOrigin) {return;}
+
+      const { type } = event.data ?? {};
+
+      if (type === 'dweb-connect-loaded') {
+        // Wallet is ready — send the authorization request.
+        popup.postMessage({
+          type        : 'dweb-connect-authorization-request',
+          did,
+          permissions : permissionRequests,
+        }, walletOrigin);
+        return;
+      }
+
+      if (type === 'dweb-connect-authorization-response') {
+        clearInterval(pollClosed);
+        cleanup();
+
+        const { delegateDid, grants } = event.data;
+
+        if (!delegateDid || !grants) {
+          // User denied the request.
+          resolve(undefined);
+          return;
+        }
+
+        resolve({
+          delegatePortableDid : delegateDid as PortableDid,
+          delegateGrants      : grants as DwnDataEncodedRecordsWriteMessage[],
+          connectedDid        : did ?? delegateDid.uri,
+        });
+      }
+    };
+
+    window.addEventListener('message', onMessage);
+  });
+}
+
+/**
+ * Probe whether a wallet supports a specific DID via a hidden iframe.
+ *
+ * Sends a `dweb-connect-support-request` message to the wallet and
+ * waits for a `dweb-connect-support-response`. Useful for checking
+ * multiple wallet URLs to find the one that manages a given DID.
+ *
+ * @param walletUrl - Base URL of the wallet to probe.
+ * @param did - The DID to check.
+ * @param timeout - Probe timeout in ms. Default: 5_000 (5 seconds).
+ * @returns `true` if the wallet manages the DID, `false` otherwise.
+ */
+async function probeWalletSupport(
+  walletUrl: string,
+  did: string,
+  timeout = 5_000,
+): Promise<boolean> {
+  if (typeof window === 'undefined') {return false;}
+
+  return new Promise<boolean>((resolve) => {
+    const iframe = document.createElement('iframe');
+    iframe.style.display = 'none';
+    iframe.src = walletUrl;
+
+    let settled = false;
+
+    const cleanup = (): void => {
+      settled = true;
+      window.removeEventListener('message', onMessage);
+      try { document.body.removeChild(iframe); } catch { /* best effort */ }
+    };
+
+    const timeoutId = setTimeout(() => {
+      if (!settled) {
+        cleanup();
+        resolve(false);
+      }
+    }, timeout);
+
+    const onMessage = (event: MessageEvent): void => {
+      const walletOrigin = new URL(walletUrl).origin;
+      if (event.origin !== walletOrigin) { return; }
+
+      const { type, supported } = event.data ?? {};
+      if (type === 'dweb-connect-support-response') {
+        clearTimeout(timeoutId);
+        cleanup();
+        resolve(!!supported);
+      }
+    };
+
+    window.addEventListener('message', onMessage);
+
+    iframe.addEventListener('load', () => {
+      const walletOrigin = new URL(walletUrl).origin;
+      iframe.contentWindow?.postMessage({
+        type: 'dweb-connect-support-request',
+        did,
+      }, walletOrigin);
+    });
+
+    document.body.appendChild(iframe);
+  });
+}
+
+export const DWebConnect = { initClient, probeWalletSupport };

package/src/index.ts

@@ -1 +1,5 @@
-export * from './web-features.js';
+export * from './web-features.js';
+export { BrowserConnectHandler, DEFAULT_WALLETS } from './browser-connect-handler.js';
+export type { BrowserConnectHandlerOptions, WalletOption } from './browser-connect-handler.js';
+export { DWebConnect } from './dweb-connect-client.js';
+export type { DWebConnectClientOptions } from './dweb-connect-client.js';