@hsuite/native-connect-angular 1.0.0

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

@@ -0,0 +1,723 @@
+/**
+ * HSuite Native Connect
+ * Copyright 2024-2025 HSuite (https://hsuite.finance)
+ *
+ * SPDX-License-Identifier: PolyForm-Noncommercial-1.0.0
+ *
+ * This file is part of HSuite Native Connect. For commercial licensing,
+ * visit https://hsuite.finance/licensing
+ */
+
+/**
+ * @file p2p-native.provider.ts
+ * @description P2P Native Provider for wallet connections (Nostr-first with P2P upgrade)
+ *
+ * Implements BaseWalletProvider for P2P connections using the Nostr-first protocol.
+ * Enables single-QR scanning for cross-device wallet connections (both mobile and desktop).
+ *
+ * **Key Features:**
+ * - Single QR code scanning (no answer QR needed!)
+ * - Nostr-first communication with automatic P2P upgrade
+ * - End-to-end encrypted (AES-GCM over Nostr, DTLS over WebRTC)
+ * - No intermediary servers required
+ * - Works on any network (WiFi, cellular, etc.)
+ *
+ * **Connection Flow:**
+ * 1. dApp generates compact channel invite (hsc:connect?i=...)
+ * 2. User scans QR with wallet (or clicks hsc: link on desktop)
+ * 3. Wallet connects via Nostr relays
+ * 4. User approves session in wallet
+ * 5. P2P upgrade happens automatically in background
+ */
+
+import { Injectable, NgZone, signal, computed, type Signal } from '@angular/core';
+import { getLogger } from '@hsuite/native-connect-sdk';
+
+import type { ConnectionStatus, ProviderMetadata, ProviderType } from '../../models/provider-types';
+import type { ConnectionConfig } from '../../models/provider-types';
+import type { UnifiedAccount } from '../../models/unified-account.model';
+import {
+  BaseWalletProvider,
+  type SignTransactionOptions,
+  type SubmitTransactionOptions,
+  type SignResult,
+  type SubmitResult,
+  type SignMessageOptions,
+  type SignMessageResult,
+} from '../base-wallet-provider';
+
+import { P2PSessionManager, type P2PSession } from './p2p-session-manager';
+
+const logger = getLogger().scoped?.('P2PNativeProvider') ?? getLogger();
+
+/**
+ * Storage key for mobile session metadata (separate from hsuite-native)
+ */
+const P2P_SESSION_STORAGE_KEY = 'hsuite.p2p.session';
+
+/**
+ * Mobile Session Persistence
+ *
+ * Stores mobile P2P session metadata to localStorage for dApp reconnection.
+ * Uses a separate key from hsuite-native to avoid conflicts.
+ */
+class P2PSessionPersistence {
+  /**
+   * @param session
+   * Persist mobile session to localStorage.
+   */
+  save(session: P2PSession): void {
+    try {
+      if (typeof window === 'undefined') return;
+      const payload = {
+        ...session,
+        timestamp: Date.now(),
+      };
+      window.localStorage.setItem(P2P_SESSION_STORAGE_KEY, JSON.stringify(payload));
+      logger.debug('Mobile session persisted', { sessionId: session.sessionId });
+    } catch (error) {
+      logger.warn('Failed to persist mobile session', { error });
+    }
+  }
+
+  /**
+   * Restore mobile session from localStorage.
+   */
+  restore(): (P2PSession & { timestamp: number }) | null {
+    try {
+      if (typeof window === 'undefined') return null;
+      const raw = window.localStorage.getItem(P2P_SESSION_STORAGE_KEY);
+      if (!raw) return null;
+      const stored = JSON.parse(raw) as P2PSession & { timestamp: number };
+      if (!stored?.sessionId) {
+        this.clear();
+        return null;
+      }
+      logger.info('Restored mobile session metadata', { sessionId: stored.sessionId });
+      return stored;
+    } catch (error) {
+      logger.warn('Failed to restore mobile session', { error });
+      return null;
+    }
+  }
+
+  /**
+   * Clear persisted mobile session.
+   */
+  clear(): void {
+    try {
+      if (typeof window === 'undefined') return;
+      window.localStorage.removeItem(P2P_SESSION_STORAGE_KEY);
+      logger.debug('Mobile session cleared');
+    } catch (error) {
+      logger.warn('Failed to clear mobile session', { error });
+    }
+  }
+
+  /**
+   * Check if a mobile session is stored.
+   */
+  hasStoredSession(): boolean {
+    try {
+      if (typeof window === 'undefined') return false;
+      return !!window.localStorage.getItem(P2P_SESSION_STORAGE_KEY);
+    } catch {
+      return false;
+    }
+  }
+}
+
+/**
+ * Connection state for the mobile native provider.
+ *
+ * States:
+ * - disconnected: No connection
+ * - generating_offer: Creating WebRTC offer for QR display
+ * - awaiting_scan: QR displayed, waiting for wallet to scan
+ * - connecting: WebRTC handshake in progress
+ * - pending_approval: WebRTC connected, waiting for wallet user to approve
+ * - connected: Session approved and fully connected
+ * - error: An error occurred
+ */
+export type P2PNativeConnectionState =
+  | 'disconnected'
+  | 'generating_offer'
+  | 'awaiting_scan'
+  | 'connecting'
+  | 'pending_approval'
+  | 'connected'
+  | 'error';
+
+/**
+ * Pairing offer result containing QR data
+ */
+export interface PairingOfferResult {
+  /** Encoded channel invite for QR code display (hsc:connect?i=...) */
+  qrData: string;
+  /** Session ID for this connection */
+  sessionId?: string;
+  /** Expiry timestamp */
+  expiresAt: number;
+}
+
+/**
+ * P2P Native Provider for cross-device wallet connections.
+ *
+ * @description
+ * Enables secure P2P wallet connections via WebRTC for mobile and cross-device
+ * scenarios. The dApp generates a QR code containing a channel invite, which
+ * the mobile wallet scans to establish a direct encrypted connection.
+ *
+ * Key Features:
+ * - **Single QR Code Flow**: No answer QR needed - just scan and connect
+ * - **Nostr-First**: Uses Nostr relays for signaling and fallback
+ * - **Automatic P2P Upgrade**: Upgrades to WebRTC for lower latency
+ * - **End-to-End Encrypted**: AES-GCM over Nostr, DTLS over WebRTC
+ * - **Session Persistence**: Supports reconnection after page reload
+ *
+ * Transport States (via `transportState` signal):
+ * - `'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
+ *
+ * @publicApi
+ */
+@Injectable({ providedIn: 'root' })
+export class P2PNativeProvider extends BaseWalletProvider {
+  readonly id = 'mobile-native';
+
+  readonly metadata: ProviderMetadata = {
+    name: 'HSuite Mobile',
+    type: 'mobile-native' as ProviderType,
+    icon: 'phone-portrait-outline',
+    description: 'Connect via QR code (P2P)',
+    features: [
+      'Direct P2P connection',
+      'End-to-end encrypted',
+      'No server required',
+      'Works on any network',
+    ],
+  };
+
+  // Internal state signals
+  private readonly _status = signal<ConnectionStatus>('disconnected');
+  private readonly _accounts = signal<UnifiedAccount[]>([]);
+  private readonly _error = signal<string | null>(null);
+  private readonly _connectionState = signal<P2PNativeConnectionState>('disconnected');
+  private readonly _pairingOffer = signal<PairingOfferResult | null>(null);
+
+  /** Session persistence for page reload recovery */
+  private readonly sessionPersistence = new P2PSessionPersistence();
+
+  // Public readonly signals
+  readonly status: Signal<ConnectionStatus> = this._status.asReadonly();
+  readonly accounts: Signal<UnifiedAccount[]> = this._accounts.asReadonly();
+  readonly error: Signal<string | null> = this._error.asReadonly();
+
+  /**
+   * Current detailed connection state
+   */
+  readonly connectionState: Signal<P2PNativeConnectionState> = this._connectionState.asReadonly();
+
+  /**
+   * Current pairing offer (if awaiting scan)
+   */
+  readonly pairingOffer: Signal<PairingOfferResult | null> = this._pairingOffer.asReadonly();
+
+  /**
+   * Whether currently awaiting wallet to scan QR
+   */
+  readonly isAwaitingScan = computed(() => this._connectionState() === 'awaiting_scan');
+
+  /**
+   * Whether a pairing offer is available
+   */
+  readonly hasPairingOffer = computed(() => this._pairingOffer() !== null);
+
+  /**
+   * Whether a persisted session exists
+   */
+  readonly hasPersistedSession = computed(() => this.sessionPersistence.hasStoredSession());
+
+  /**
+   * Transport state for the P2P connection.
+   * Values: 'nostr-only' | 'upgrading' | 'p2p-connected' | 'p2p-failed'
+   *
+   * This allows the UI to show the current transport layer being used.
+   */
+  readonly transportState = computed(() => this.sessionManager.p2pState());
+
+  /**
+   * @param sessionManager
+   * @param ngZone
+   */
+  constructor(
+    private readonly sessionManager: P2PSessionManager,
+    private readonly ngZone: NgZone,
+  ) {
+    super();
+    // CRITICAL: Pass NgZone to session manager so signal updates from
+    // Nostr/WebSocket callbacks (which fire outside Angular zone) trigger
+    // Angular change detection. Without this, walletContext.activeAccount
+    // stays null after session approval.
+    this.sessionManager.setNgZone(this.ngZone);
+    this.setupSessionManagerListeners();
+    this.restorePersistedSession();
+  }
+
+  /**
+   * Restore session from localStorage on page load.
+   * Sets accounts and status from persisted data.
+   * Note: This only restores metadata - the actual WebRTC connection
+   * will need to be re-established via QR pairing.
+   */
+  private restorePersistedSession(): void {
+    const stored = this.sessionPersistence.restore();
+    if (stored) {
+      logger.info('Restoring persisted mobile session', {
+        sessionId: stored.sessionId,
+        accountCount: stored.accounts?.length ?? 0,
+      });
+
+      // Restore accounts with proper providerId
+      if (stored.accounts?.length) {
+        const accountsWithProvider = this.ensureProviderIdOnAccounts(stored.accounts);
+        this._accounts.set(accountsWithProvider);
+      }
+
+      // Note: We don't set connected status because WebRTC needs re-pairing
+      // The persisted data is for account info only
+      logger.debug('Mobile session metadata restored (requires re-pairing for connection)');
+    }
+  }
+
+  /**
+   * Creates a pairing offer for QR code display.
+   *
+   * @description
+   * Generates a channel invite encoded for QR display. The mobile wallet
+   * scans this QR code to establish a connection via Nostr relays with
+   * automatic P2P upgrade.
+   *
+   * The returned `qrData` is a compact `hsc:connect?i=...` URL that contains:
+   * - Channel ID and encryption keys
+   * - App metadata (name, ID)
+   * - Relay endpoints for communication
+   *
+   * @param config - Connection configuration specifying ledger and network
+   *
+   * @returns Promise resolving to pairing offer containing QR data and expiry
+   *
+   * @throws {Error} If offer generation fails
+   */
+  async createPairingOffer(config: ConnectionConfig): Promise<PairingOfferResult> {
+    logger.info('Creating pairing offer', { config });
+
+    try {
+      this._connectionState.set('generating_offer');
+      this._error.set(null);
+
+      // Extract common properties based on config type
+      const appId = 'appId' in config ? (config.appId ?? 'hsuite-dapp') : 'hsuite-dapp';
+      const appName = 'appName' in config ? (config.appName ?? 'HSuite dApp') : 'HSuite dApp';
+      const ledgerId = 'ledgerId' in config ? (config.ledgerId ?? 'hedera') : 'hedera';
+      const networkId = config.networkId ?? 'testnet';
+
+      const result = await this.sessionManager.createPairingOffer({
+        appId,
+        appName,
+        ledgerId,
+        networkId,
+      });
+
+      const offerResult: PairingOfferResult = {
+        qrData: result.qrData,
+        sessionId: result.sessionId,
+        expiresAt: Date.now() + 120 * 1000, // 2 minutes
+      };
+
+      this._pairingOffer.set(offerResult);
+      this._connectionState.set('awaiting_scan');
+      this._status.set('connecting');
+
+      logger.info('Pairing offer created', {
+        qrDataLength: result.qrData.length,
+        expiresAt: offerResult.expiresAt,
+      });
+
+      return offerResult;
+    } catch (error) {
+      logger.error('Failed to create pairing offer', { error });
+      this._connectionState.set('error');
+      this._status.set('error');
+      this._error.set(error instanceof Error ? error.message : 'Failed to create pairing offer');
+      throw error;
+    }
+  }
+
+  /**
+   * Refresh the pairing offer (e.g., when expired).
+   *
+   * @param config - Connection configuration
+   * @returns Promise resolving to new pairing offer
+   */
+  async refreshPairingOffer(config: ConnectionConfig): Promise<PairingOfferResult> {
+    logger.debug('Refreshing pairing offer');
+
+    // Cancel any existing offer
+    await this.sessionManager.cancelPairingOffer();
+
+    return this.createPairingOffer(config);
+  }
+
+  /**
+   * Register callback for when peer connects.
+   *
+   * @param callback - Function to call when connection is established
+   */
+  onPeerConnected(callback: () => void): void {
+    this.sessionManager.onConnected(() => {
+      callback();
+    });
+  }
+
+  /**
+   * Waits for the wallet to connect and approve the session.
+   *
+   * @description
+   * Call this after {@link createPairingOffer} to block until the wallet user
+   * completes the connection flow. This is the single-QR flow - no answer
+   * scanning is required.
+   *
+   * The method resolves when all of the following occur:
+   * 1. Wallet scans the QR code
+   * 2. Wallet connects via Nostr relay
+   * 3. User approves the session in the wallet
+   *
+   * Upon success, the session is automatically persisted for reconnection.
+   *
+   * @returns Promise resolving to the approved session with account information
+   *
+   * @throws {Error} If connection fails or is rejected
+   * @throws {Error} If no pairing offer was created
+   */
+  async waitForSessionApproval(): Promise<P2PSession> {
+    logger.info('Waiting for wallet to connect and approve session');
+    this._connectionState.set('pending_approval');
+
+    try {
+      // This blocks until wallet connects via Nostr and user approves
+      const session = await this.sessionManager.waitForSessionApproval();
+
+      // Connection state will be updated by sessionManager callbacks, but also set here for immediate update
+      this._connectionState.set('connected');
+      this._status.set('connected');
+
+      // Ensure accounts have providerId set correctly
+      if (session?.accounts) {
+        const accountsWithProvider = this.ensureProviderIdOnAccounts(session.accounts);
+        this._accounts.set(accountsWithProvider);
+      }
+
+      // Persist session for page reload recovery
+      this.sessionPersistence.save(session);
+
+      return session;
+    } catch (error) {
+      logger.error('Session approval failed', { error });
+      this._connectionState.set('error');
+      throw error;
+    }
+  }
+
+  // ========== BaseWalletProvider Implementation ==========
+
+  /**
+   * Connects to a wallet via the P2P pairing flow.
+   *
+   * @description
+   * Initiates the pairing offer flow and waits for connection. For more
+   * control over QR display timing, use {@link createPairingOffer} and
+   * {@link waitForSessionApproval} separately.
+   *
+   * This method:
+   * 1. Creates a pairing offer
+   * 2. Updates `pairingOffer` signal with QR data
+   * 3. Waits up to 2 minutes for wallet to connect
+   *
+   * @param config - Connection configuration
+   *
+   * @throws {Error} If already connected (no-op)
+   * @throws {Error} If connection times out (2 minutes)
+   */
+  async connect(config: ConnectionConfig): Promise<void> {
+    logger.info('Connect called', { config });
+
+    // If already connected, no-op
+    if (this._status() === 'connected') {
+      logger.debug('Already connected');
+      return;
+    }
+
+    // Create pairing offer and wait for connection
+    await this.createPairingOffer(config);
+
+    // Wait for connection to complete
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        reject(new Error('Connection timeout'));
+      }, 120000); // 2 minute timeout
+
+      this.sessionManager.onConnected(() => {
+        clearTimeout(timeout);
+        resolve();
+      });
+
+      this.sessionManager.onError((error: Error) => {
+        clearTimeout(timeout);
+        reject(error);
+      });
+    });
+  }
+
+  /**
+   * Disconnects from the wallet and clears session.
+   *
+   * @description
+   * Terminates the P2P session, clears all state signals, and removes
+   * persisted session data. The wallet is notified of the disconnection.
+   */
+  async disconnect(): Promise<void> {
+    logger.info('Disconnecting');
+
+    try {
+      await this.sessionManager.terminateSession();
+    } finally {
+      this._status.set('disconnected');
+      this._connectionState.set('disconnected');
+      this._accounts.set([]);
+      this._pairingOffer.set(null);
+      this._error.set(null);
+
+      // Clear persisted session
+      this.sessionPersistence.clear();
+    }
+  }
+
+  /**
+   * Signs a transaction without submitting it.
+   *
+   * @description
+   * Sends the transaction to the connected wallet for signing. The wallet
+   * displays transaction details and prompts the user for approval.
+   *
+   * @param options - Transaction signing options
+   *
+   * @returns Promise resolving to signed payload and signature
+   *
+   * @throws {Error} If not connected to wallet
+   * @throws {Error} If user rejects signing
+   */
+  async signTransaction(options: SignTransactionOptions): Promise<SignResult> {
+    if (this._status() !== 'connected') {
+      throw new Error('Not connected to wallet');
+    }
+
+    logger.info('Signing transaction', { account: options.accountAddress });
+
+    const result = await this.sessionManager.signTransaction({
+      accountAddress: options.accountAddress,
+      payload: options.payload,
+      ledgerId: options.ledgerId,
+      networkId: options.networkId,
+    });
+
+    return {
+      signedPayload: result.signedPayload,
+      signature: result.signature,
+      metadata: result.metadata,
+    };
+  }
+
+  /**
+   * Signs and submits a transaction to the blockchain.
+   *
+   * @description
+   * Performs atomic sign and submit in a single operation. Supports batch
+   * transactions when isBatch is true.
+   *
+   * @param options - Transaction submission options
+   *
+   * @returns Promise resolving to transaction ID and hash
+   *
+   * @throws {Error} If not connected to wallet
+   * @throws {Error} If user rejects or transaction fails
+   */
+  async submitTransaction(options: SubmitTransactionOptions): Promise<SubmitResult> {
+    if (this._status() !== 'connected') {
+      throw new Error('Not connected to wallet');
+    }
+
+    logger.info('Submitting transaction', { account: options.accountAddress });
+
+    const result = await this.sessionManager.submitTransaction({
+      accountAddress: options.accountAddress,
+      payload: options.payload,
+      ledgerId: options.ledgerId,
+      networkId: options.networkId,
+      isBatch: options.isBatch,
+      batchKey: options.batchKey,
+      innerTransactions: options.innerTransactions,
+    });
+
+    return {
+      transactionId: result.transactionId,
+      transactionHash: result.transactionHash,
+      metadata: result.metadata,
+    };
+  }
+
+  /**
+   * Signs and executes a transaction atomically in a single prompt.
+   *
+   * @description
+   * Delegates to {@link submitTransaction}. This method exists so that
+   * {@link UnifiedWalletService.signAndExecuteTransaction} can detect native
+   * atomic sign+submit support on the provider (via duck-typing) and avoid
+   * its fallback path that chains separate signTransaction + submitTransaction
+   * calls. Mirrors the pattern used by HsuiteNativeProvider and the
+   * WalletConnect signers.
+   *
+   * @param options - Transaction submission options
+   *
+   * @returns Promise resolving to submission result with transaction ID
+   */
+  async signAndExecuteTransaction(options: SubmitTransactionOptions): Promise<SubmitResult> {
+    return this.submitTransaction(options);
+  }
+
+  /**
+   * Signs an arbitrary message for authentication or verification.
+   *
+   * @description
+   * Requests the wallet to sign a non-transaction message. Used for
+   * authentication challenges, DAO voting, or off-chain signatures.
+   *
+   * @param options - Message signing options
+   *
+   * @returns Promise resolving to signature and public key
+   *
+   * @throws {Error} If not connected to wallet
+   * @throws {Error} If user rejects signing
+   */
+  async signMessage(options: SignMessageOptions): Promise<SignMessageResult> {
+    if (this._status() !== 'connected') {
+      throw new Error('Not connected to wallet');
+    }
+
+    logger.info('Signing message', { account: options.accountAddress });
+
+    const result = await this.sessionManager.signMessage({
+      accountAddress: options.accountAddress,
+      message: options.message,
+      encoding: options.encoding,
+      ledgerId: options.ledgerId,
+      networkId: options.networkId,
+    });
+
+    return {
+      signature: result.signature,
+      publicKey: result.publicKey,
+      metadata: result.metadata,
+    };
+  }
+
+  /**
+   * Checks if P2P provider is available in the current environment.
+   *
+   * @description
+   * P2P Native requires WebRTC support (RTCPeerConnection). This is available
+   * in all modern browsers and most mobile WebViews.
+   *
+   * @returns Promise resolving to true if WebRTC is available
+   */
+  async isAvailable(): Promise<boolean> {
+    // Check for WebRTC support
+    return typeof RTCPeerConnection !== 'undefined';
+  }
+
+  // ========== Private Methods ==========
+
+  /**
+   * Set up listeners for session manager events
+   */
+  private setupSessionManagerListeners(): void {
+    // Connection established — wrap in NgZone to ensure Angular change
+    // detection picks up signal updates from Nostr/WebSocket callbacks
+    this.sessionManager.onConnected((session) => {
+      logger.info('Session connected', { sessionId: session?.id });
+      this.ngZone.run(() => {
+        this._connectionState.set('connected');
+        this._status.set('connected');
+        this._pairingOffer.set(null);
+
+        // Update accounts from session - ensure providerId is set
+        if (session?.accounts) {
+          const accountsWithProvider = this.ensureProviderIdOnAccounts(session.accounts);
+          this._accounts.set(accountsWithProvider);
+        }
+      });
+
+      // Persist session for page reload recovery
+      if (session) {
+        this.sessionPersistence.save(session);
+      }
+    });
+
+    // Session terminated
+    this.sessionManager.onDisconnected(() => {
+      logger.info('Session disconnected');
+      this.ngZone.run(() => {
+        this._connectionState.set('disconnected');
+        this._status.set('disconnected');
+        this._accounts.set([]);
+      });
+
+      // Clear persisted session
+      this.sessionPersistence.clear();
+    });
+
+    // Error occurred
+    this.sessionManager.onError((error: Error) => {
+      logger.error('Session error', { error });
+      this.ngZone.run(() => {
+        this._connectionState.set('error');
+        this._status.set('error');
+        this._error.set(error.message);
+      });
+    });
+
+    // Accounts updated
+    this.sessionManager.onAccountsChanged((accounts) => {
+      logger.debug('Accounts updated', { count: accounts.length });
+      this.ngZone.run(() => {
+        const accountsWithProvider = this.ensureProviderIdOnAccounts(accounts);
+        this._accounts.set(accountsWithProvider);
+      });
+    });
+  }
+
+  /**
+   * Ensure all accounts have providerId and providerType set correctly
+   * @param accounts
+   */
+  private ensureProviderIdOnAccounts(accounts: UnifiedAccount[]): UnifiedAccount[] {
+    return accounts.map((account) => ({
+      ...account,
+      id: account.id || `${this.id}-${account.address}`,
+      providerId: this.id,
+      providerType: this.metadata.type,
+    }));
+  }
+}