@enbox/browser 0.3.43 → 0.3.45

package/src/browser-connect-handler.ts

@@ -10,8 +10,9 @@
 import type { ConnectPermissionRequest } from '@enbox/connect';
 import type { ConnectHandler, ConnectResult } from '@enbox/auth';
 
-import { connectViaPopup } from './dweb-connect-client.js';
-import { showWalletSelector } from './ui/wallet-selector.js';
+import { runConnectModal } from './ui/connect-modal.js';
+
+import type { ConnectMethod } from './ui/connect-modal.js';
 
 /** A wallet entry shown in the wallet selector modal. */
 export interface WalletOption {
@@ -85,17 +86,44 @@ export interface BrowserConnectHandlerOptions {
    */
   appIcon?: string;
 
+  /**
+   * Preferred connect method on open: `'phone'` (QR / deep link via the
+   * relay) or `'browser'` (wallet popup on this device). Overrides the
+   * remembered choice.
+   * @default 'phone'
+   */
+  preferredMethod?: ConnectMethod;
+
+  /**
+   * Remember the successful method + wallet in localStorage and pre-shape
+   * the next connect session accordingly.
+   * @default true
+   */
+  rememberChoice?: boolean;
+
+  /**
+   * Relay base URL override for the phone path. When omitted, each wallet's
+   * `connectServerUrl` is discovered from its `/.well-known/enbox-connect`
+   * document.
+   */
+  connectServerUrl?: string;
+
+  /**
+   * Path appended to the wallet origin to form the phone path's QR /
+   * deep-link target.
+   * @default '/connect/app'
+   */
+  relayWalletPath?: string;
 }
 
 /**
- * Create a browser-native connect handler using DWeb Connect
- * (popup + postMessage).
+ * Create a browser-native connect handler over the connect modal.
  *
- * 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.
+ * The modal owns the whole session on one surface: the phone path (a QR /
+ * deep link over the relay, with pairing-code entry) is the default, the
+ * in-browser wallet popup is the alternate, and the wallet catalog plus
+ * custom-URL entry live in a disclosure. It resolves with the delegate
+ * credentials on success and `undefined` when the user denies.
  *
  * @example
  * ```ts
@@ -115,29 +143,31 @@ export function BrowserConnectHandler(
 ): ConnectHandler {
   const {
     wallets = DEFAULT_WALLETS,
-    walletUrl: fixedWalletUrl,
+    walletUrl,
     timeout,
     appName,
     appIcon,
+    preferredMethod,
+    rememberChoice,
+    connectServerUrl,
+    relayWalletPath,
   } = 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 over the connect kernel.
-      return connectViaPopup({
+      return runConnectModal({
+        wallets,
         walletUrl,
-        permissionRequests: params.permissionRequests,
-        timeout,
+        preferredMethod,
+        rememberChoice,
         appName,
-        appIcon,
+        appIcon            : appIcon ?? `${window.location.origin}/favicon.ico`,
+        connectServerUrl,
+        relayWalletPath,
+        timeout,
+        permissionRequests : params.permissionRequests,
       });
     },
   };

package/src/dweb-connect-client.ts

@@ -328,7 +328,7 @@ export type PopupConnectOptions = {
 };
 
 /** Collects self-reported environment hints for the wallet's session display. */
-function collectBrowserClientMetadata(): ConnectClientMetadata {
+export function collectBrowserClientMetadata(): ConnectClientMetadata {
   const resolvedOptions = Intl.DateTimeFormat().resolvedOptions();
   const languages = Array.isArray(globalThis.navigator.languages)
     ? globalThis.navigator.languages.filter((language) => typeof language === 'string' && language.length > 0)

package/src/index.ts

@@ -104,8 +104,14 @@ export type {
   DWebConnectRequestMessage,
   DWebConnectResponseMessage,
 } from './dweb-connect-messages.js';
-export type { WalletSelectorOptions } from './ui/wallet-selector.js';
-export { probeWalletWellKnown, showWalletSelector, WALLET_WELL_KNOWN_PATH } from './ui/wallet-selector.js';
+export { fetchWalletWellKnown, probeWalletWellKnown, WALLET_WELL_KNOWN_PATH } from './ui/wallet-well-known.js';
+export type { WalletWellKnownDocument } from './ui/wallet-well-known.js';
+export { discoverWalletConnectServerUrl, runConnectModal } from './ui/connect-modal.js';
+export type { ConnectMethod, ConnectModalDeps, ConnectModalOptions } from './ui/connect-modal.js';
+export { MAX_PIN_ATTEMPTS, RelayConnectCancelledError, runRelayConnect } from './relay-connect-runner.js';
+export type { RelayConnectOptions } from './relay-connect-runner.js';
+export { encodeQr, qrToSvg } from './ui/qr.js';
+export type { QrCode, QrSvgOptions } from './ui/qr.js';
 
 // ─── Convenience re-exports for dapps ───────────────────────────
 //

package/src/relay-connect-runner.ts

@@ -0,0 +1,209 @@
+/**
+ * Relay connect runner — the dapp side of the QR/deep-link connect flow,
+ * with interactive PIN retry.
+ *
+ * This mirrors the `@enbox/connect` kernel `ConnectClient` step-for-step and
+ * is composed entirely from the kernel's exported primitives (`sealRequest`,
+ * `openResponse`, `RelayClientTransport`); no cryptography is reimplemented
+ * here. It exists as a separate orchestrator for one reason the kernel
+ * client cannot express today: **PIN retry against the delivered response**.
+ * `ConnectClient` collects the PIN once and opens the response once, so a
+ * mistyped code fails the whole handshake — the wallet user would have to
+ * scan and approve again. The connect modal instead keeps the sealed
+ * response and re-runs `openResponse` per attempt, which is safe because
+ * opening is a pure decrypt-and-verify step.
+ *
+ * If the kernel later grows a PIN-attempts seam, this module collapses into
+ * `ConnectClient` usage.
+ *
+ * @module
+ */
+
+import type { Jwk } from '@enbox/crypto';
+import type {
+  ConnectClientMetadata,
+  ConnectPermissionRequest,
+  ConnectRequest,
+  ConnectResult,
+  WalletUriHandoff,
+} from '@enbox/connect';
+
+import { DidJwk } from '@enbox/dids';
+import { X25519 } from '@enbox/crypto';
+import {
+  CONNECT_DENIED_TOKEN,
+  openResponse,
+  randomToken,
+  RelayClientTransport,
+  sealRequest,
+} from '@enbox/connect';
+
+/** Maximum interactive PIN attempts before the handshake fails. */
+export const MAX_PIN_ATTEMPTS = 6;
+
+/** Thrown internally when a relay handshake is cancelled by the UI. */
+export class RelayConnectCancelledError extends Error {
+  constructor() {
+    super('[@enbox/browser] Relay connect cancelled.');
+    this.name = 'RelayConnectCancelledError';
+  }
+}
+
+/** Options for {@link runRelayConnect}. */
+export interface RelayConnectOptions {
+  /** Relay base URL (the wallet's `connectServerUrl`). */
+  connectServerUrl: string;
+
+  /** Wallet URI the request pointer is attached to (QR / deep-link target). */
+  walletUri: string;
+
+  /** The user-friendly name of the app, shown in the wallet consent UI. */
+  appName: string;
+
+  /** Optional icon URL for the app, shown in the wallet consent UI. */
+  appIcon?: string;
+
+  /** Optional client/environment metadata for wallet session display. */
+  clientMetadata?: ConnectClientMetadata;
+
+  /** DWN protocols and permission scopes being requested. */
+  permissionRequests: ConnectPermissionRequest[];
+
+  /** Total milliseconds to poll the relay for a wallet response. */
+  timeoutMs?: number;
+
+  /** Milliseconds between relay polling attempts. */
+  pollIntervalMs?: number;
+
+  /**
+   * Receives the wallet URI handoff (with the request pointer TTL) as soon
+   * as the request is delivered — render it as a QR code or deep link.
+   */
+  onWalletUriReady: (handoff: WalletUriHandoff) => void;
+
+  /**
+   * Collects one PIN attempt from the user. Called again (with the attempt
+   * number, 1-based, and the previous failure) after a wrong code, up to
+   * {@link MAX_PIN_ATTEMPTS} times.
+   */
+  requestPin: (attempt: number, previousError?: Error) => Promise<string>;
+
+  /**
+   * Cancellation signal: when it settles, polling stops and the handshake
+   * rejects with {@link RelayConnectCancelledError}.
+   */
+  cancelled?: Promise<never> | undefined;
+
+  /**
+   * Invoked once when the relay reports the wallet has claimed (fetched)
+   * the pushed request — the app can show "phone connected" progress.
+   */
+  onClaimed?: () => void;
+
+  /** Transport factory override (tests). */
+  createTransport?: (options: {
+    connectServerUrl: string;
+    walletUri: string;
+    timeoutMs?: number;
+    pollIntervalMs?: number;
+    onClaimed?: () => void;
+  }) => Pick<RelayClientTransport, 'requestProfile' | 'deliverRequest' | 'awaitResponse' | 'requiresPin'>;
+}
+
+/**
+ * Runs one relay-mediated connect handshake end-to-end and returns the
+ * delegated credentials, or `undefined` when the user denied in the wallet.
+ */
+export async function runRelayConnect(options: RelayConnectOptions): Promise<ConnectResult | undefined> {
+  const createTransport = options.createTransport
+    ?? ((transportOptions): RelayClientTransport => new RelayClientTransport(transportOptions));
+
+  const transport = createTransport({
+    connectServerUrl : options.connectServerUrl,
+    walletUri        : options.walletUri,
+    timeoutMs        : options.timeoutMs,
+    pollIntervalMs   : options.pollIntervalMs,
+    onClaimed        : options.onClaimed,
+  });
+
+  // Ephemeral client DID for request signing and response addressing, and a
+  // fresh X25519 pair the wallet seals the response to — same shape as the
+  // kernel `ConnectClient`.
+  const clientDid = await DidJwk.create();
+  const responsePrivateKey = await X25519.generateKey();
+  const responsePublicKey: Jwk = { kty: 'OKP', crv: 'X25519', x: responsePrivateKey.x };
+
+  const nonce = randomToken();
+  const state = randomToken();
+
+  const profile = await transport.requestProfile(state);
+
+  const request: ConnectRequest = {
+    clientDid           : clientDid.uri,
+    appName             : options.appName,
+    appIcon             : options.appIcon,
+    clientMetadata      : options.clientMetadata,
+    permissionRequests  : options.permissionRequests,
+    supportedDidMethods : ['did:dht', 'did:jwk'],
+    nonce,
+    state,
+    responseKey         : responsePublicKey,
+    reply               : profile.reply,
+  };
+
+  const requestJwe = await sealRequest({ request, signer: clientDid, encryption: profile.encryption });
+
+  const handoff = await transport.deliverRequest(requestJwe);
+  if (handoff !== undefined) {
+    options.onWalletUriReady(handoff);
+  }
+
+  const race = options.cancelled === undefined
+    ? transport.awaitResponse()
+    : Promise.race([transport.awaitResponse(), options.cancelled]);
+
+  const responseCiphertext = await race;
+  if (responseCiphertext === CONNECT_DENIED_TOKEN) {
+    return undefined;
+  }
+
+  // Interactive PIN loop: opening is a pure decrypt-and-verify step, so a
+  // wrong code costs one more attempt, not a whole new wallet approval.
+  // Errors raised by the kernel's value checks carry a 'Connect:' prefix and
+  // indicate a protocol violation, not a mistyped code — those fail closed.
+  let lastError: Error | undefined;
+  for (let attempt = 1; attempt <= MAX_PIN_ATTEMPTS; attempt++) {
+    const pin = await (options.cancelled === undefined
+      ? options.requestPin(attempt, lastError)
+      : Promise.race([options.requestPin(attempt, lastError), options.cancelled]));
+
+    try {
+      const response = await openResponse({
+        jwe                 : responseCiphertext,
+        recipientPrivateKey : responsePrivateKey,
+        expected            : { clientDid: clientDid.uri, nonce, state },
+        pin,
+      });
+
+      if (response.delegatePortableDid === undefined) {
+        throw new Error('Connect: wallet response omitted `delegatePortableDid`.');
+      }
+
+      return {
+        delegatePortableDid : response.delegatePortableDid,
+        delegateGrants      : response.delegateGrants,
+        connectedDid        : response.providerDid,
+        sessionRevocations  : response.sessionRevocations,
+      };
+    } catch (error) {
+      const failure = error instanceof Error ? error : new Error(String(error));
+      if (failure.message.startsWith('Connect:')) {
+        // Structural/value-check failure — retrying the PIN cannot help.
+        throw failure;
+      }
+      lastError = failure;
+    }
+  }
+
+  throw new Error(`[@enbox/browser] The pairing code did not match after ${MAX_PIN_ATTEMPTS} attempts.`);
+}