@hsuite/native-connect-angular 1.0.0

package/src/lib/providers/p2p-native/p2p-session-manager.ts

@@ -0,0 +1,695 @@
+/**
+ * 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-session-manager.ts
+ * @description Session management for P2P Native connections (dApp-side)
+ *
+ * Manages Nostr-first P2P connections for wallet pairing (both mobile and desktop).
+ * The dApp creates a session invite QR code that the wallet scans.
+ * Communication starts via Nostr relays and upgrades to WebRTC P2P when possible.
+ *
+ * **Architecture Notes:**
+ * - Uses the unified ChannelClient for Nostr/P2P communication
+ * - Single QR code scanning (no 2-phase exchange)
+ * - Session negotiation via Nostr, then P2P upgrade
+ * - RPC communication over best available transport
+ * - Session ownership remains with the wallet
+ */
+
+import { Injectable, signal, type Signal, NgZone } from '@angular/core';
+import {
+  ChannelClient,
+  type ChannelInvite,
+  type ChannelState,
+  type TransportState,
+  type ChannelAccount,
+  encodeChannelInvite,
+  getLogger,
+} from '@hsuite/native-connect-sdk';
+
+import type { UnifiedAccount } from '../../models/unified-account.model';
+
+const logger = getLogger().scoped?.('P2PSessionManager') ?? getLogger();
+
+/**
+ * Connection state for P2P native sessions.
+ *
+ * States:
+ * - idle: No connection attempt in progress
+ * - creating_offer: Generating session invite for QR code
+ * - awaiting_connection: QR displayed, waiting for wallet to scan and connect
+ * - pending_approval: Wallet connected, waiting for user to approve session
+ * - connected: Session approved and fully connected
+ * - disconnected: Previously connected, now disconnected
+ * - error: Connection or handshake error occurred
+ */
+export type P2PConnectionState =
+  | 'idle'
+  | 'creating_offer'
+  | 'awaiting_connection'
+  | 'pending_approval'
+  | 'connected'
+  | 'disconnected'
+  | 'error';
+
+/**
+ * Options for creating a pairing offer
+ */
+export interface CreateOfferOptions {
+  appId: string;
+  appName: string;
+  ledgerId: string;
+  networkId: string;
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Result of creating a pairing offer
+ */
+export interface CreateOfferResult {
+  /** Encoded QR data (nostr+p2p://...) */
+  qrData: string;
+  /** Channel ID for this connection attempt */
+  sessionId: string;
+}
+
+/**
+ * Managed session data
+ */
+export interface P2PSession {
+  id: string;
+  sessionId: string;
+  appId: string;
+  appName: string;
+  ledgerId: string;
+  networkId: string;
+  accounts: UnifiedAccount[];
+  permissions: string[];
+  connectedAt: number;
+}
+
+/**
+ * Transaction options for RPC calls
+ */
+export interface TransactionOptions {
+  accountAddress: string;
+  payload: string;
+  ledgerId?: string;
+  networkId?: string;
+  isBatch?: boolean;
+  batchKey?: string;
+  innerTransactions?: Array<{ payload: string; description?: string }>;
+}
+
+/**
+ * Message signing options
+ */
+export interface MessageSigningOptions {
+  accountAddress: string;
+  message: string;
+  encoding?: 'utf-8' | 'base64';
+  ledgerId?: string;
+  networkId?: string;
+}
+
+/**
+ * Mobile Native Session Manager
+ *
+ * Manages Nostr-first P2P connections for mobile wallet pairing.
+ * Creates and displays QR codes that mobile wallets can scan
+ * to establish a direct, end-to-end encrypted connection.
+ *
+ * Uses single QR code scanning with Nostr for initial signaling
+ * and automatic P2P upgrade when possible.
+ *
+ * This implementation uses the unified ChannelClient from the new channel protocol.
+ */
+@Injectable({ providedIn: 'root' })
+export class P2PSessionManager {
+  // Private state
+  private readonly _connectionState = signal<P2PConnectionState>('idle');
+  private readonly _currentSession = signal<P2PSession | null>(null);
+  private readonly _p2pState = signal<TransportState>('nostr-only');
+
+  // Channel client
+  private client?: ChannelClient;
+  private currentInvite?: ChannelInvite;
+
+  // Callbacks
+  private connectedCallbacks: Array<(session: P2PSession) => void> = [];
+  private disconnectedCallbacks: Array<() => void> = [];
+  private errorCallbacks: Array<(error: Error) => void> = [];
+  private accountsChangedCallbacks: Array<(accounts: UnifiedAccount[]) => void> = [];
+
+  // NgZone for change detection
+  private zone?: NgZone;
+
+  // Session negotiation state
+  private sessionApprovalPromise?: {
+    resolve: (session: P2PSession) => void;
+    reject: (error: Error) => void;
+  };
+
+  /**
+   *
+   */
+  constructor() {}
+
+  /**
+   * Set NgZone for Angular change detection
+   * @param zone
+   */
+  setNgZone(zone: NgZone): void {
+    this.zone = zone;
+  }
+
+  /**
+   * Current connection state
+   */
+  get connectionState(): Signal<P2PConnectionState> {
+    return this._connectionState.asReadonly();
+  }
+
+  /**
+   * Current session
+   */
+  get currentSession(): Signal<P2PSession | null> {
+    return this._currentSession.asReadonly();
+  }
+
+  /**
+   * Current P2P upgrade state
+   */
+  get p2pState(): Signal<TransportState> {
+    return this._p2pState.asReadonly();
+  }
+
+  /**
+   * Create a pairing offer for QR code display.
+   *
+   * Generates a compact session invite encoded for QR code display.
+   * The invite contains the channel ID, encryption key, and Nostr relays.
+   *
+   * @param options - Offer creation options
+   * @returns Promise resolving to offer result with QR data
+   */
+  async createPairingOffer(options: CreateOfferOptions): Promise<CreateOfferResult> {
+    logger.info('Creating pairing offer (Nostr-first)', { options });
+
+    try {
+      this.runInZone(() => this._connectionState.set('creating_offer'));
+
+      // Clean up any existing client
+      await this.cleanup(false);
+
+      // Create new channel client with state/account callbacks.
+      // The polling in startStateSync() also reads client.state, but these
+      // callbacks ensure immediate handling of state transitions — critical
+      // when the wallet approves via Nostr and the approval event arrives
+      // between poll ticks.
+      this.client = new ChannelClient({
+        p2p: { enabled: true },
+        onStateChange: (state: ChannelState) => {
+          logger.debug('ChannelClient state callback', { state });
+          const accounts = this.client?.accounts ?? [];
+          this.handleStateChange(state, accounts);
+        },
+        onAccountsChange: (accounts: ChannelAccount[]) => {
+          logger.debug('ChannelClient accounts callback', { count: accounts.length });
+          const state = this.client?.state ?? 'idle';
+          this.handleStateChange(state, accounts);
+        },
+      });
+
+      // Connect and get invite. Always include the dApp's origin so the
+      // wallet can show the user where the request is coming from.
+      const resolvedOrigin =
+        typeof window !== 'undefined' && window.location ? window.location.origin : undefined;
+
+      const invite = await this.client.connect({
+        type: 'session',
+        app: {
+          id: options.appId,
+          name: options.appName,
+          origin: resolvedOrigin,
+        },
+        context: {
+          ledgerId: options.ledgerId,
+          networkId: options.networkId,
+        },
+        permissions: ['sign', 'submit'],
+      });
+
+      this.currentInvite = invite;
+
+      // Encode invite for QR code
+      const qrData = encodeChannelInvite(invite);
+
+      this.runInZone(() => this._connectionState.set('awaiting_connection'));
+
+      logger.info('Pairing offer created', {
+        sessionId: invite.id.slice(0, 8),
+        qrDataLength: qrData.length,
+      });
+
+      // Start polling for state changes
+      this.startStateSync();
+
+      return { qrData, sessionId: invite.id };
+    } catch (error) {
+      logger.error('Failed to create pairing offer', { error });
+      this.runInZone(() => this._connectionState.set('error'));
+      this.notifyError(error instanceof Error ? error : new Error('Failed to create offer'));
+      throw error;
+    }
+  }
+
+  /**
+   * Wait for wallet to connect and approve the session.
+   *
+   * This method blocks until the wallet scans the QR, connects via Nostr,
+   * and the user approves the session.
+   *
+   * @returns Promise resolving to the approved session
+   */
+  async waitForSessionApproval(): Promise<P2PSession> {
+    if (!this.client || !this.currentInvite) {
+      throw new Error('No active pairing offer - call createPairingOffer first');
+    }
+
+    logger.info('Waiting for wallet to connect and approve session...');
+
+    return new Promise<P2PSession>((resolve, reject) => {
+      this.sessionApprovalPromise = { resolve, reject };
+    });
+  }
+
+  /**
+   * Cancel the current pairing offer.
+   *
+   * Cleans up the transport without fully disconnecting.
+   */
+  async cancelPairingOffer(): Promise<void> {
+    logger.debug('Cancelling pairing offer');
+
+    if (this.sessionApprovalPromise) {
+      this.sessionApprovalPromise.reject(new Error('Pairing cancelled'));
+      this.sessionApprovalPromise = undefined;
+    }
+
+    await this.cleanup();
+    this.runInZone(() => this._connectionState.set('idle'));
+  }
+
+  /**
+   * @param callback
+   * Register callback for when peer connects
+   */
+  onConnected(callback: (session: P2PSession) => void): void {
+    this.connectedCallbacks.push(callback);
+  }
+
+  /**
+   * @param callback
+   * Register callback for disconnection
+   */
+  onDisconnected(callback: () => void): void {
+    this.disconnectedCallbacks.push(callback);
+  }
+
+  /**
+   * @param callback
+   * Register callback for errors
+   */
+  onError(callback: (error: Error) => void): void {
+    this.errorCallbacks.push(callback);
+  }
+
+  /**
+   * @param callback
+   * Register callback for accounts changes
+   */
+  onAccountsChanged(callback: (accounts: UnifiedAccount[]) => void): void {
+    this.accountsChangedCallbacks.push(callback);
+  }
+
+  /**
+   * @param options
+   * Sign a transaction via RPC
+   */
+  async signTransaction(options: TransactionOptions): Promise<{
+    signedPayload: string;
+    signature?: string;
+    metadata?: Record<string, unknown>;
+  }> {
+    this.requireSession();
+
+    logger.info('Signing transaction', { account: options.accountAddress });
+
+    if (!this.client) {
+      throw new Error('Not connected');
+    }
+
+    const response = await this.client.request<{
+      signedPayload?: string;
+      signedTransaction?: string;
+      signature?: string;
+      metadata?: Record<string, unknown>;
+    }>('ledger/sign', {
+      accountAddress: options.accountAddress,
+      payload: options.payload,
+      ledgerId: options.ledgerId,
+      networkId: options.networkId,
+    });
+
+    return {
+      signedPayload: response.signedPayload || response.signedTransaction || '',
+      signature: response.signature,
+      metadata: response.metadata,
+    };
+  }
+
+  /**
+   * @param options
+   * Submit a transaction via RPC
+   */
+  async submitTransaction(options: TransactionOptions): Promise<{
+    transactionId: string;
+    transactionHash?: string;
+    metadata?: Record<string, unknown>;
+  }> {
+    this.requireSession();
+
+    logger.info('Submitting transaction', { account: options.accountAddress });
+
+    if (!this.client) {
+      throw new Error('Not connected');
+    }
+
+    const response = await this.client.request<{
+      transactionId?: string;
+      transactionHash?: string;
+      metadata?: Record<string, unknown>;
+    }>('ledger/signAndSubmit', {
+      accountAddress: options.accountAddress,
+      payload: options.payload,
+      ledgerId: options.ledgerId,
+      networkId: options.networkId,
+      isBatch: options.isBatch,
+      batchKey: options.batchKey,
+      innerTransactions: options.innerTransactions,
+    });
+
+    return {
+      transactionId: response.transactionId || '',
+      transactionHash: response.transactionHash,
+      metadata: response.metadata,
+    };
+  }
+
+  /**
+   * @param options
+   * Sign an arbitrary message via RPC
+   */
+  async signMessage(options: MessageSigningOptions): Promise<{
+    signature: string;
+    publicKey?: string;
+    // §21.3 extended shape — passes the adapter's full MessageSignResult
+    // through to the dApp. Optional for backwards compatibility with
+    // pre-§21.3 wallets that only return signature + publicKey.
+    algorithm?: 'ed25519' | 'ecdsa_secp256k1' | 'secp256k1';
+    encoding?: 'utf-8' | 'base64';
+    caipChainId?: string;
+    messageLength?: number;
+    metadata?: Record<string, unknown>;
+  }> {
+    this.requireSession();
+
+    logger.info('Signing message', { account: options.accountAddress });
+
+    if (!this.client) {
+      throw new Error('Not connected');
+    }
+
+    const response = await this.client.request<{
+      signature?: string;
+      publicKey?: string;
+      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,
+    });
+
+    return {
+      signature: response.signature || '',
+      publicKey: response.publicKey,
+      algorithm: response.algorithm,
+      encoding: response.encoding,
+      caipChainId: response.caipChainId,
+      messageLength: response.messageLength,
+      metadata: response.metadata,
+    };
+  }
+
+  /**
+   * Terminate the current session
+   */
+  async terminateSession(): Promise<void> {
+    logger.info('Terminating session');
+
+    if (this.client) {
+      await this.client.disconnect();
+    }
+
+    await this.cleanup();
+    this.runInZone(() => {
+      this._currentSession.set(null);
+      this._connectionState.set('disconnected');
+    });
+    this.notifyDisconnected();
+  }
+
+  // ========== Private Methods ==========
+
+  /**
+   * Run function in NgZone if available
+   * @param fn
+   */
+  private runInZone(fn: () => void): void {
+    if (this.zone) {
+      this.zone.run(fn);
+    } else {
+      fn();
+    }
+  }
+
+  /**
+   * Start polling for state changes from the channel client
+   */
+  private startStateSync(): void {
+    const checkState = () => {
+      if (!this.client) return;
+
+      const clientState = this.client.state;
+      const clientAccounts = this.client.accounts;
+      const clientTransport = this.client.transportState;
+
+      // Update transport state
+      this.runInZone(() => this._p2pState.set(clientTransport));
+
+      // Map channel state to P2P connection state
+      this.handleStateChange(clientState, clientAccounts);
+
+      // Continue polling while not disconnected
+      if (this.client && clientState !== 'disconnected' && clientState !== 'error') {
+        setTimeout(checkState, 100);
+      }
+    };
+
+    setTimeout(checkState, 100);
+  }
+
+  /**
+   * Handle channel state changes
+   * @param state
+   * @param accounts
+   */
+  private handleStateChange(state: ChannelState, accounts: ChannelAccount[]): void {
+    switch (state) {
+      case 'pending':
+        if (this._connectionState() === 'awaiting_connection') {
+          this.runInZone(() => this._connectionState.set('pending_approval'));
+        }
+        break;
+
+      case 'active':
+      case 'approved':
+        if (this._connectionState() !== 'connected') {
+          const session = this.createSession(accounts);
+          this.runInZone(() => {
+            this._currentSession.set(session);
+            this._connectionState.set('connected');
+          });
+
+          // Resolve the approval promise
+          if (this.sessionApprovalPromise) {
+            this.sessionApprovalPromise.resolve(session);
+            this.sessionApprovalPromise = undefined;
+          }
+
+          this.notifyConnected(session);
+        }
+        break;
+
+      case 'disconnected':
+        this.handleDisconnection('Wallet disconnected');
+        break;
+
+      case 'error':
+        this.runInZone(() => this._connectionState.set('error'));
+        if (this.sessionApprovalPromise) {
+          this.sessionApprovalPromise.reject(new Error('Connection error'));
+          this.sessionApprovalPromise = undefined;
+        }
+        break;
+    }
+  }
+
+  /**
+   * Create a P2PSession from channel accounts
+   * @param accounts
+   */
+  private createSession(accounts: ChannelAccount[]): P2PSession {
+    const invite = this.currentInvite;
+
+    return {
+      id: crypto.randomUUID(),
+      sessionId: invite?.id || crypto.randomUUID(),
+      appId: invite?.app.id || 'hsuite-dapp',
+      appName: invite?.app.name || 'HSuite dApp',
+      ledgerId: invite?.context.ledgerId || 'hedera',
+      networkId: invite?.context.networkId || 'testnet',
+      accounts: accounts.map((acc, index) => ({
+        id: `p2p-${acc.address}`,
+        address: acc.address,
+        label: acc.alias || `Account ${index + 1}`,
+        ledgerId: acc.ledgerId,
+        networkId: acc.networkId,
+        providerId: 'p2p-native',
+        providerType: 'hsuite-native' as const,
+        metadata: {
+          publicKey: acc.publicKey,
+        },
+      })),
+      permissions: this.client?.permissions || [],
+      connectedAt: Date.now(),
+    };
+  }
+
+  /**
+   * Handle disconnection
+   * @param reason
+   */
+  private handleDisconnection(reason: string): void {
+    logger.info('Handling disconnection', { reason });
+    this.cleanup();
+    this.runInZone(() => {
+      this._currentSession.set(null);
+      this._connectionState.set('disconnected');
+    });
+    this.notifyDisconnected();
+  }
+
+  /**
+   * Require active session or throw
+   */
+  private requireSession(): P2PSession {
+    const session = this._currentSession();
+    if (!session) {
+      throw new Error('No active session');
+    }
+    return session;
+  }
+
+  /**
+   * Clean up resources.
+   *
+   * @param rejectPending - If true, reject pending promises with error.
+   *                        If false, clear them silently (for new session creation).
+   */
+  private async cleanup(rejectPending = true): Promise<void> {
+    // Reject pending approval if requested
+    if (this.sessionApprovalPromise && rejectPending) {
+      this.sessionApprovalPromise.reject(new Error('Connection closed'));
+    }
+    this.sessionApprovalPromise = undefined;
+
+    if (this.client) {
+      try {
+        await this.client.disconnect();
+      } catch {
+        // Ignore disconnect errors during cleanup
+      }
+      this.client = undefined;
+    }
+
+    this.currentInvite = undefined;
+    this.runInZone(() => this._p2pState.set('nostr-only'));
+  }
+
+  /**
+   * Notify connected callbacks
+   * @param session
+   */
+  private notifyConnected(session: P2PSession): void {
+    for (const callback of this.connectedCallbacks) {
+      try {
+        callback(session);
+      } catch (error) {
+        logger.error('Connected callback error', { error });
+      }
+    }
+  }
+
+  /**
+   * Notify disconnected callbacks
+   */
+  private notifyDisconnected(): void {
+    for (const callback of this.disconnectedCallbacks) {
+      try {
+        callback();
+      } catch (error) {
+        logger.error('Disconnected callback error', { error });
+      }
+    }
+  }
+
+  /**
+   * Notify error callbacks
+   * @param error
+   */
+  private notifyError(error: Error): void {
+    for (const callback of this.errorCallbacks) {
+      try {
+        callback(error);
+      } catch (err) {
+        logger.error('Error callback error', { err });
+      }
+    }
+  }
+}