@hsuite/native-connect-angular 1.0.0

package/src/lib/providers/hsuite-native-provider.ts

@@ -0,0 +1,754 @@
+/**
+ * @file Provider implementation for HSuite Native Connect protocol.
+ * @module providers/hsuite-native-provider
+ *
+ * @description
+ * HsuiteNativeProvider implements the {@link BaseWalletProvider} interface for the
+ * HSuite Native Connect protocol. This provider enables secure communication between
+ * dApps and HSuite Wallet using the `hsc:` protocol over Nostr relays with automatic
+ * WebRTC P2P upgrade.
+ *
+ * Key Features:
+ * - **Local-First Discovery**: Uses BroadcastChannel for instant same-browser wallet detection
+ * - **Nostr Communication**: Uses Nostr relays for encrypted channel messaging
+ * - **Automatic P2P Upgrade**: Upgrades to direct WebRTC when possible for lower latency
+ * - **Session Persistence**: Supports automatic reconnection after page reload
+ * - **Cross-Platform**: Works with desktop browsers, mobile browsers, and native apps
+ *
+ * Connection Flow:
+ * ```
+ * 1. dApp calls connect() with configuration
+ * 2. Provider checks local discovery for same-browser wallets (instant!)
+ * 3. If wallet found -> sends invite via BroadcastChannel (<1ms)
+ * 4. If not found -> opens wallet tab/window with invite URL
+ * 5. Wallet receives invite and establishes channel via Nostr relay
+ * 6. User approves connection in wallet
+ * 7. Channel becomes active, accounts are available
+ * 8. P2P upgrade happens automatically in background
+ * ```
+ */
+
+import { Injectable, signal, computed, inject, effect, NgZone } from '@angular/core';
+import { getLogger, LocalDiscoveryService } from '@hsuite/native-connect-sdk';
+
+import type {
+  ConnectionStatus,
+  ProviderMetadata,
+  ConnectionConfig,
+  HsuiteNativeConfig,
+} from '../models/provider-types';
+import { DEFAULT_WALLET_URL } from '../models/provider-types';
+import type { UnifiedAccount } from '../models/unified-account.model';
+import { WalletEventBus } from '../services/wallet-event-bus.service';
+
+import {
+  BaseWalletProvider,
+  SignTransactionOptions,
+  SubmitTransactionOptions,
+  SignResult,
+  SubmitResult,
+  SignMessageOptions,
+  SignMessageResult,
+} from './base-wallet-provider';
+import { ChannelClientService } from './hsuite-native/channel-client.service';
+
+const logger = getLogger().scoped?.('HsuiteNativeProvider') ?? getLogger();
+
+/**
+ * HSuite Native Connect Provider.
+ *
+ * @description
+ * Angular injectable service that manages wallet connections via the HSuite Native
+ * Connect protocol. This provider uses the unified channel system for secure,
+ * encrypted communication between dApps and the HSuite Wallet.
+ *
+ * Architecture:
+ * - Uses {@link ChannelClientService} for unified channel-based communication
+ * - Implements {@link BaseWalletProvider} interface for integration with {@link UnifiedWalletService}
+ * - Supports both session (1:1 dApp-wallet) and party (N:N multisig) channels
+ * - Auto-registers with UnifiedWalletService on injection
+ *
+ * Transport States (exposed via `transportState` signal):
+ * - `'idle'` - No active connection
+ * - `'nostr-only'` - Connected via Nostr relay only
+ * - `'upgrading'` - P2P upgrade in progress
+ * - `'p2p-connected'` - Direct P2P connection established
+ * - `'p2p-failed'` - P2P upgrade failed, using Nostr fallback
+ *
+ * @Component({
+ *   template: `
+ *     <ion-badge [color]="transportColor()">
+ *       {{ transportState() }}
+ *     </ion-badge>
+ *   `
+ * })
+ * export class ConnectionStatus {
+ *   private provider = inject(HsuiteNativeProvider);
+ *
+ *   transportState = this.provider.transportState;
+ *
+ *   transportColor = computed(() => {
+ *     const state = this.transportState();
+ *     return state === 'p2p-connected' ? 'success' : 'warning';
+ *   });
+ * }
+ * ```
+ *
+ * @publicApi
+ */
+@Injectable({ providedIn: 'root' })
+export class HsuiteNativeProvider extends BaseWalletProvider {
+  private readonly eventBus = inject(WalletEventBus);
+  private readonly zone = inject(NgZone);
+  private readonly channelService = inject(ChannelClientService);
+
+  readonly id = 'hsuite-native';
+
+  readonly metadata: ProviderMetadata = {
+    id: this.id,
+    name: 'HSuite Native',
+    type: 'hsuite-native',
+    description: 'Connect via HSuite Native Connect protocol',
+    supportsMultipleAccounts: true,
+  };
+
+  /**
+   * Error signal (reactive)
+   */
+  readonly error = signal<string | null>(null);
+
+  // Track previous connection state for disconnect detection
+  private previouslyConnected = false;
+
+  /**
+   * Local discovery service instance.
+   * Uses BroadcastChannel for instant, private, same-browser wallet discovery.
+   */
+  private localDiscoveryService: LocalDiscoveryService | null = null;
+
+  /**
+   *
+   */
+  constructor() {
+    super();
+
+    // Initialize local discovery service for same-browser wallet detection
+    this.initializeLocalDiscovery();
+
+    // Synchronize error state from channel service
+    effect(() => {
+      const channelError = this.channelService.error();
+      if (channelError) {
+        this.error.set(channelError);
+      }
+    });
+
+    // Listen to channel state changes to detect wallet-initiated disconnects
+    effect(() => {
+      const status = this.status();
+      const isConnected = this.channelService.isConnected();
+
+      // If we were connected but now disconnected, emit disconnect event
+      if (this.previouslyConnected && !isConnected && status === 'disconnected') {
+        logger.info('[HsuiteNativeProvider] Channel terminated');
+        this.eventBus.disconnected.emit({
+          providerId: this.id,
+          providerType: 'hsuite-native',
+          reason: 'session_terminated',
+          timestamp: Date.now(),
+        });
+      }
+
+      // Update tracking state
+      this.previouslyConnected = isConnected;
+    });
+
+    // Attempt automatic reconnect when session exists after reload
+    void this.attemptReconnect().catch((error) => {
+      logger.debug('[HsuiteNativeProvider] Auto-reconnect skipped', { error });
+    });
+  }
+
+  /**
+   * Initialize local discovery for same-browser wallet detection.
+   * Uses BroadcastChannel for instant, private discovery.
+   * Cross-device connections use QR/URL flow (no discovery needed).
+   */
+  private initializeLocalDiscovery(): void {
+    this.localDiscoveryService = LocalDiscoveryService.getDAppInstance();
+    this.localDiscoveryService.start();
+  }
+
+  /**
+   * Maps the internal channel state to the provider connection status.
+   *
+   * @description
+   * Computed signal that translates ChannelClientService states to
+   * standard ConnectionStatus values for UI binding.
+   *
+   * @returns Current connection status
+   */
+  readonly status = computed<ConnectionStatus>(() => {
+    const state = this.channelService.state();
+
+    switch (state) {
+      case 'idle':
+        return 'idle';
+      case 'connecting':
+      case 'pending':
+        return 'connecting';
+      case 'active':
+      case 'approved':
+        return 'connected';
+      case 'disconnected':
+        return 'disconnected';
+      case 'error':
+        return 'error';
+      default:
+        return 'idle';
+    }
+  });
+
+  /**
+   * Current transport state (nostr-only, upgrading, p2p-connected, p2p-failed).
+   * Use this to show users whether they're connected via Nostr relay or P2P.
+   */
+  readonly transportState = computed(() => this.channelService.transportState());
+
+  /**
+   * Connected accounts from the wallet in UnifiedAccount format.
+   *
+   * @description
+   * Computed signal that exposes wallet accounts from the channel service
+   * in the standard UnifiedAccount format for UI binding.
+   *
+   * @returns Array of connected accounts (empty when disconnected)
+   */
+  readonly accounts = computed<UnifiedAccount[]>(() => {
+    return this.channelService.unifiedAccounts();
+  });
+
+  /**
+   * Check if provider is connected
+   */
+  override isConnected(): boolean {
+    return this.channelService.isConnected();
+  }
+
+  /**
+   * Connects to HSuite Wallet via the Native Connect protocol.
+   *
+   * @description
+   * Initiates a connection to HSuite Wallet using the optimal method for the
+   * current platform:
+   *
+   * **Desktop Browsers**:
+   * 1. Checks if wallet is already online via Nostr discovery (instant!)
+   * 2. If found, sends invite directly via relay
+   * 3. If not found, opens wallet in new tab/window
+   *
+   * **Mobile Browsers**:
+   * 1. Tries hsuite: deep link to open native wallet app
+   * 2. Falls back to opening wallet in same tab (PWA) or new tab
+   *
+   * The connection completes when the wallet user approves the session.
+   *
+   * @param config - HSuite Native connection configuration
+   *
+   * @throws {Error} If configuration is invalid
+   * @throws {Error} If connection times out (default 120 seconds)
+   * @throws {Error} If popup is blocked and wallet cannot be opened
+   */
+  override async connect(config: ConnectionConfig): Promise<void> {
+    if (!this.isHsuiteNativeConfig(config)) {
+      throw new Error('Invalid HSuite Native configuration');
+    }
+
+    // Guard: Don't start a new connection if already connecting
+    const currentStatus = this.status();
+    if (currentStatus === 'connecting') {
+      logger.warn('Connection already in progress, ignoring duplicate request');
+      return;
+    }
+
+    logger.info('Connecting to HSuite Wallet via unified channel protocol', { config });
+
+    try {
+      const invite = await this.channelService.connect({
+        type: 'session',
+        appId: config.appId || 'hsuite-dapp',
+        appName: config.appName || 'HSuite dApp',
+        ledgerId: config.ledgerId,
+        networkId: config.networkId,
+        walletUrl: config.walletUrl || DEFAULT_WALLET_URL,
+      });
+
+      // Open wallet with invite URL
+      const walletUrl = config.walletUrl || DEFAULT_WALLET_URL;
+      const inviteUrl = this.channelService.getWalletInviteUrl(invite, walletUrl);
+
+      // Open wallet using Nostr-based discovery (works cross-origin, cross-port)
+      await this.openWalletWindow(inviteUrl, walletUrl, config);
+
+      // Wait for connection to be established
+      await this.waitForConnection();
+
+      // Run in NgZone to trigger Angular change detection
+      this.zone.run(() => {
+        const accounts = this.accounts();
+        this.eventBus.connected.emit({
+          providerId: this.id,
+          providerType: 'hsuite-native',
+          accounts,
+          timestamp: Date.now(),
+        });
+
+        logger.info('Connected successfully via unified channel', {
+          channelId: invite.id.slice(0, 8),
+          accountCount: accounts.length,
+        });
+      });
+    } catch (error) {
+      logger.error('Connection failed', { error });
+      throw error;
+    }
+  }
+
+  /**
+   * Open wallet window with LOCAL-FIRST discovery.
+   *
+   * LOCAL DISCOVERY MODEL:
+   * 1. Check if wallet is online in same browser via BroadcastChannel (instant!)
+   * 2. If not immediately found, wait briefly (500ms) for wallet heartbeat
+   * 3. If wallet found → send invite via BroadcastChannel (<1ms), focus existing tab
+   * 4. If not found → open wallet tab or use QR/deep link
+   *
+   * Cross-device connections use QR/URL flow - the invite is self-contained,
+   * no discovery needed.
+   *
+   * @param inviteUrl - Full URL with invite parameter
+   * @param walletBaseUrl - Base URL of the wallet
+   * @param config - Connection configuration with app metadata
+   */
+  private async openWalletWindow(
+    inviteUrl: string,
+    walletBaseUrl: string,
+    config?: HsuiteNativeConfig,
+  ): Promise<void> {
+    const isMobile = /iPhone|iPad|iPod|Android/i.test(navigator.userAgent);
+
+    // LOCAL-FIRST DISCOVERY
+    // Wait briefly for wallet heartbeat before opening new tab
+    if (this.localDiscoveryService?.active) {
+      // Wait up to 500ms for a wallet to announce itself
+      const wallet = await this.localDiscoveryService.waitForWallet({
+        timeoutMs: 500,
+        ledgerId: config?.ledgerId,
+      });
+
+      if (wallet) {
+        // Send invite directly via BroadcastChannel - instant, no network!
+        this.localDiscoveryService.sendInvite(
+          wallet.fingerprint,
+          inviteUrl,
+          config?.appId,
+          config?.appName,
+        );
+        logger.info('[HsuiteNativeProvider] Sent invite via local discovery', {
+          wallet: wallet.fingerprint.slice(0, 8),
+        });
+        return;
+      }
+    }
+
+    // MOBILE: Prefer same-tab navigation for PWA wallet
+    if (isMobile) {
+      const isSameOrigin = this.isSameOrigin(walletBaseUrl);
+
+      if (isSameOrigin) {
+        window.location.href = inviteUrl;
+        return;
+      } else {
+        // Try deep link first
+        const deepLinkUrl = inviteUrl.replace(/^https?:/, 'hsuite:');
+        try {
+          window.location.href = deepLinkUrl;
+          await new Promise((resolve) => setTimeout(resolve, 500));
+        } catch {
+          // Deep link failed, continue to open tab
+        }
+      }
+    }
+
+    // FALLBACK: Open wallet in a new tab (for same-browser) or show QR (cross-device)
+    // §29.8 SOC2 CC6.1: noopener,noreferrer prevents a compromised dApp-supplied
+    // inviteUrl from hijacking the dApp tab via window.opener. A side effect is
+    // that window.open() returns null, so we can no longer use the return value
+    // to detect popup-blocked; modern browsers surface that via their own UI
+    // and the caller's waitForConnection() timeout will error out if the user
+    // dismissed the popup dialog without allowing.
+    const walletWindow = window.open(inviteUrl, 'hsuite-wallet', 'noopener,noreferrer');
+    // .focus() is a no-op with noopener (walletWindow === null); fresh tabs
+    // are already focused in every mainstream browser.
+    void walletWindow;
+  }
+
+  /**
+   * Check if a URL is same origin as current page.
+   * @param url
+   */
+  private isSameOrigin(url: string): boolean {
+    try {
+      const walletOrigin = new URL(url).origin;
+      return walletOrigin === window.location.origin;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Wait for channel connection to be established
+   * @param timeoutMs
+   */
+  private async waitForConnection(timeoutMs = 120000): Promise<void> {
+    const startTime = Date.now();
+
+    return new Promise((resolve, reject) => {
+      const checkConnection = () => {
+        if (this.channelService.isConnected()) {
+          resolve();
+          return;
+        }
+
+        const state = this.channelService.state();
+        if (state === 'error') {
+          reject(new Error(this.channelService.error() || 'Connection failed'));
+          return;
+        }
+
+        // Also handle disconnected state (wallet rejected or terminated)
+        if (state === 'disconnected') {
+          reject(new Error(this.channelService.error() || 'Connection rejected by wallet'));
+          return;
+        }
+
+        if (Date.now() - startTime > timeoutMs) {
+          reject(new Error('Connection timeout'));
+          return;
+        }
+
+        setTimeout(checkConnection, 100);
+      };
+
+      checkConnection();
+    });
+  }
+
+  /**
+   * Disconnects from the HSuite Wallet.
+   *
+   * @description
+   * Terminates the channel connection and clears session state. The wallet
+   * is notified of the disconnection. Emits a 'disconnected' event via
+   * WalletEventBus regardless of success or failure.
+   *
+   * @throws {Error} If disconnection fails (event still emitted)
+   */
+  override async disconnect(): Promise<void> {
+    logger.info('Disconnecting from HSuite Wallet');
+
+    try {
+      await this.channelService.disconnect();
+
+      // Emit disconnection event
+      this.eventBus.disconnected.emit({
+        providerId: this.id,
+        providerType: 'hsuite-native',
+        reason: 'user_initiated',
+        timestamp: Date.now(),
+      });
+
+      logger.info('Disconnected successfully');
+    } catch (error) {
+      logger.error('Disconnection failed', { error });
+      // Still emit event even if disconnect fails
+      this.eventBus.disconnected.emit({
+        providerId: this.id,
+        providerType: 'hsuite-native',
+        reason: 'error',
+        timestamp: Date.now(),
+      });
+      throw error;
+    }
+  }
+
+  /**
+   * Signs a transaction without submitting it to the network.
+   *
+   * @description
+   * Sends the transaction payload to the wallet for signing. The wallet
+   * displays the transaction details and prompts the user for approval.
+   * If approved, the signed transaction is returned.
+   *
+   * @param options - Transaction signing options
+   *
+   * @returns Promise resolving to the signing result with signed payload
+   *
+   * @throws {Error} If user rejects the signing request
+   * @throws {Error} If wallet is not connected
+   * @throws {Error} If channel communication fails
+   */
+  override async signTransaction(options: SignTransactionOptions): Promise<SignResult> {
+    logger.info('Signing transaction', { options });
+
+    try {
+      const response = await this.channelService.signTransaction({
+        accountAddress: options.accountAddress,
+        payload: options.payload,
+        ledgerId: options.ledgerId,
+        networkId: options.networkId,
+      });
+
+      logger.info('Transaction signed');
+
+      return {
+        signedPayload: response.signedPayload || '',
+        signature: response.signature,
+        metadata: response.metadata,
+      };
+    } catch (error) {
+      logger.error('Transaction signing failed', { error });
+      throw error;
+    }
+  }
+
+  /**
+   * Signs and executes a transaction atomically in a single prompt.
+   *
+   * @description
+   * Performs sign and submit as a single atomic operation with one user
+   * approval prompt. This is the recommended method for transaction submission
+   * as it provides better UX and matches WalletConnect's behavior.
+   *
+   * Called by {@link UnifiedWalletService.signAndExecuteTransaction} to ensure
+   * consistent single-prompt behavior across all provider types.
+   *
+   * @param options - Transaction submission options
+   *
+   * @returns Promise resolving to submission result with transaction ID
+   *
+   * @throws {Error} If user rejects the transaction
+   * @throws {Error} If wallet is not connected
+   * @throws {Error} If transaction submission fails
+   */
+  async signAndExecuteTransaction(options: SubmitTransactionOptions): Promise<SubmitResult> {
+    logger.info('signAndExecuteTransaction called (single prompt)', {
+      accountAddress: options.accountAddress,
+      ledgerId: options.ledgerId,
+      networkId: options.networkId,
+    });
+
+    return this.submitTransactionInternal(options);
+  }
+
+  /**
+   * Signs and submits a transaction to the blockchain.
+   *
+   * @description
+   * The **preferred method** for submitting transactions. Performs sign and
+   * submit as a single atomic operation requiring only ONE user approval.
+   *
+   * Advantages over separate sign/submit:
+   * - Single wallet prompt (better UX)
+   * - Matches WalletConnect's `hedera_signAndExecuteTransaction` behavior
+   * - Atomic operation (no partial state)
+   *
+   * @param options - Transaction submission options
+   *
+   * @returns Promise resolving to submission result with transaction ID
+   *
+   * @throws {Error} If user rejects the transaction
+   * @throws {Error} If wallet is not connected
+   * @throws {Error} If transaction submission fails
+   */
+  override async submitTransaction(options: SubmitTransactionOptions): Promise<SubmitResult> {
+    return this.submitTransactionInternal(options);
+  }
+
+  /**
+   * Internal implementation of sign and submit.
+   * Both submitTransaction() and signAndExecuteTransaction() delegate here.
+   *
+   * @param options
+   */
+  private async submitTransactionInternal(
+    options: SubmitTransactionOptions,
+  ): Promise<SubmitResult> {
+    logger.info('Signing and submitting transaction (single prompt)', {
+      accountAddress: options.accountAddress,
+      ledgerId: options.ledgerId,
+      networkId: options.networkId,
+    });
+
+    try {
+      const response = await this.channelService.signAndSubmitTransaction({
+        accountAddress: options.accountAddress,
+        payload: options.payload,
+        ledgerId: options.ledgerId,
+        networkId: options.networkId,
+        // Pass batch transaction fields if present
+        ...(options.isBatch && {
+          isBatch: options.isBatch,
+          batchKey: options.batchKey,
+          innerTransactions: options.innerTransactions,
+        }),
+      });
+
+      logger.info('Transaction signed and submitted successfully', {
+        transactionId: response.transactionId,
+        transactionHash: response.transactionHash?.substring(0, 16),
+      });
+
+      return {
+        transactionId: response.transactionId,
+        transactionHash: response.transactionHash,
+        metadata: response.metadata,
+      };
+    } catch (error) {
+      logger.error('Transaction sign+submit failed', { error });
+      throw error;
+    }
+  }
+
+  /**
+   * Signs an arbitrary message for authentication or verification.
+   *
+   * @description
+   * Requests the wallet to sign a non-transaction message. Common use cases:
+   * - Authentication challenges (prove account ownership)
+   * - DAO voting
+   * - Off-chain signatures
+   * - Message verification
+   *
+   * @param options - Message signing options
+   *
+   * @returns Promise resolving to signature result
+   *
+   * @throws {Error} If user rejects the signing request
+   * @throws {Error} If wallet is not connected
+   */
+  override async signMessage(options: SignMessageOptions): Promise<SignMessageResult> {
+    logger.info('Signing message', {
+      accountAddress: options.accountAddress,
+      encoding: options.encoding,
+      messageLength: options.message?.length,
+    });
+
+    try {
+      const response = await this.channelService.request<{
+        signature?: string;
+        publicKey?: string;
+        // §21.3 extended shape — new wallets include these fields.
+        // Older wallets (pre-§21.3) omit them; the optional chain below
+        // keeps us backwards-compatible with both.
+        algorithm?: 'ed25519' | 'ecdsa_secp256k1' | 'secp256k1';
+        encoding?: 'utf-8' | 'base64';
+        caipChainId?: string;
+        messageLength?: number;
+        metadata?: Record<string, unknown>;
+      }>('ledger/signMessage', {
+        accountAddress: options.accountAddress,
+        message: options.message,
+        encoding: options.encoding || 'utf-8',
+        ledgerId: options.ledgerId,
+        networkId: options.networkId,
+      });
+
+      logger.info('Message signed successfully', {
+        algorithm: response.algorithm,
+        caipChainId: response.caipChainId,
+      });
+
+      // Pass ALL fields through so the dApp's TransactionService sees the
+      // full MessageSignResult shape (§21.3 strict end-to-end contract).
+      return {
+        signature: response.signature || '',
+        publicKey: response.publicKey,
+        algorithm: response.algorithm,
+        encoding: response.encoding,
+        caipChainId: response.caipChainId,
+        messageLength: response.messageLength,
+        metadata: response.metadata,
+      };
+    } catch (error) {
+      logger.error('Message signing failed', { error });
+      throw error;
+    }
+  }
+
+  /**
+   * Checks if HSuite Native provider is available.
+   *
+   * @description
+   * HSuite Native is always available because it can use either:
+   * - Direct Nostr relay connection (if wallet is online)
+   * - Opening wallet in a new browser tab/window
+   * - Deep linking to native app on mobile
+   *
+   * @returns Promise always resolving to true
+   */
+  override async isAvailable(): Promise<boolean> {
+    // HSuite Native is always available (can open wallet window or use extension)
+    return true;
+  }
+
+  /**
+   * Attempts to restore a previous session and reconnect automatically.
+   *
+   * @description
+   * Checks for stored session data and attempts to re-establish the wallet
+   * connection without requiring user interaction. This is called automatically
+   * on provider initialization.
+   *
+   * If successful, emits a 'sessionRestored' event via WalletEventBus.
+   *
+   * @returns Promise resolving to true if reconnection succeeded, false otherwise
+   */
+  async attemptReconnect(): Promise<boolean> {
+    logger.info('Attempting reconnect via unified channel');
+
+    try {
+      const success = await this.channelService.attemptRestore();
+
+      if (success) {
+        const accounts = this.accounts();
+        const invite = this.channelService.currentInvite();
+
+        this.eventBus.sessionRestored.emit({
+          providerId: this.id,
+          sessionKey: invite?.id || '',
+          accounts,
+          metadata: { autoReconnected: true },
+          timestamp: Date.now(),
+        });
+
+        logger.info('Reconnect successful');
+      } else {
+        logger.warn('Reconnect failed - no session or unable to connect');
+      }
+
+      return success;
+    } catch (error) {
+      logger.error('Reconnect failed', { error });
+      return false;
+    }
+  }
+
+  /**
+   * Type guard for HSuite Native config
+   * @param config
+   */
+  private isHsuiteNativeConfig(config: ConnectionConfig): config is HsuiteNativeConfig {
+    return config.type === 'hsuite-native';
+  }
+}