@hsuite/native-connect-angular 1.0.0

package/src/lib/providers/base-wallet-provider.ts

@@ -0,0 +1,351 @@
+/**
+ * @file Abstract base class for wallet connection providers.
+ * @module providers/base-wallet-provider
+ *
+ * @description
+ * BaseWalletProvider defines the common interface that all wallet providers must implement.
+ * It ensures consistency across different wallet connection protocols while allowing
+ * provider-specific implementations.
+ *
+ * The Angular SDK includes three built-in providers:
+ * - **HsuiteNativeProvider**: HSuite Native Connect protocol
+ * - **WalletConnectV2Provider**: WalletConnect v2 protocol
+ * - **P2PNativeProvider**: Direct P2P connections via WebRTC
+ *
+ * Custom providers can extend this class to integrate additional wallet types.
+ *
+ * @Injectable({ providedIn: 'root' })
+ * export class MyCustomProvider extends BaseWalletProvider {
+ *   readonly id = 'my-custom-wallet';
+ *
+ *   readonly metadata: ProviderMetadata = {
+ *     id: this.id,
+ *     name: 'My Custom Wallet',
+ *     type: 'custom',
+ *     description: 'Custom wallet integration',
+ *     supportsMultipleAccounts: false,
+ *   };
+ *
+ *   readonly status = signal<ConnectionStatus>('disconnected');
+ *   readonly accounts = signal<UnifiedAccount[]>([]);
+ *   readonly error = signal<string | null>(null);
+ *
+ *   async connect(config: ConnectionConfig): Promise<void> {
+ *     // Implementation
+ *   }
+ *
+ *   async disconnect(): Promise<void> {
+ *     // Implementation
+ *   }
+ *
+ *   // ... other abstract methods
+ * }
+ * ```
+ */
+
+import type { Signal } from '@angular/core';
+
+import type { ConnectionConfig } from '../models/connection-config.model';
+import type { ConnectionStatus, ProviderMetadata } from '../models/provider-types';
+import type { UnifiedAccount } from '../models/unified-account.model';
+
+/**
+ * Options for signing a blockchain transaction.
+ *
+ * @description
+ * Configuration object passed to {@link BaseWalletProvider.signTransaction}.
+ */
+export interface SignTransactionOptions {
+  /** The account address to sign with (e.g., '0.0.123456' for Hedera) */
+  accountAddress: string;
+  /** Serialized transaction payload (format depends on ledger type) */
+  payload: string;
+  /** Ledger identifier (e.g., 'hedera', 'xrpl') */
+  ledgerId?: string;
+  /** Network identifier (e.g., 'mainnet', 'testnet') */
+  networkId?: string;
+}
+
+/**
+ * Options for submitting a transaction to the blockchain.
+ *
+ * @description
+ * Extends {@link SignTransactionOptions} with batch transaction support.
+ * Configuration object passed to {@link BaseWalletProvider.submitTransaction}.
+ */
+export interface SubmitTransactionOptions extends SignTransactionOptions {
+  /** Whether this is a batch/atomic transaction */
+  isBatch?: boolean;
+  /** Unique identifier for batch grouping */
+  batchKey?: string;
+  /** Inner transactions within the batch */
+  innerTransactions?: Array<{ payload: string; description?: string }>;
+}
+
+/**
+ * Result of a transaction signing operation.
+ *
+ * @description
+ * Returned by {@link BaseWalletProvider.signTransaction} upon successful signing.
+ */
+export interface SignResult {
+  /** The transaction payload with signature applied */
+  signedPayload: string;
+  /** Raw signature bytes (optional, format depends on ledger) */
+  signature?: string;
+  /** Additional metadata from the wallet */
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Result of a transaction submission.
+ *
+ * @description
+ * Returned by {@link BaseWalletProvider.submitTransaction} upon successful submission.
+ */
+export interface SubmitResult {
+  /** Ledger-specific transaction identifier (e.g., '0.0.123@1234567890.123' for Hedera) */
+  transactionId: string;
+  /** Transaction hash/ID on the blockchain */
+  transactionHash?: string;
+  /** Additional metadata from the wallet */
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Options for signing an arbitrary message.
+ *
+ * @description
+ * Configuration object passed to {@link BaseWalletProvider.signMessage}.
+ * Used for authentication, DAO voting, and other non-transaction signatures.
+ */
+export interface SignMessageOptions {
+  /** The account address to sign with */
+  accountAddress: string;
+  /** The message to sign (plain text or base64 encoded) */
+  message: string;
+  /** Encoding of the message: 'utf-8' (default) or 'base64' */
+  encoding?: 'utf-8' | 'base64';
+  /** Ledger identifier (e.g., 'hedera', 'xrpl') */
+  ledgerId?: string;
+  /** Network identifier (e.g., 'mainnet', 'testnet') */
+  networkId?: string;
+}
+
+/**
+ * Result of a message signing operation.
+ *
+ * @description
+ * Returned by {@link BaseWalletProvider.signMessage} upon successful signing.
+ */
+export interface SignMessageResult {
+  /** The signature over the domain-separated message (hex, format depends on ledger). */
+  signature: string;
+  /** The public key used for signing (for verification). */
+  publicKey?: string;
+  /**
+   * Algorithm label (§21.3 — added for deterministic verification across
+   * chains). Absent on legacy responses from older wallets.
+   */
+  algorithm?: 'ed25519' | 'ecdsa_secp256k1' | 'secp256k1';
+  /**
+   * Echo of the request's encoding. Callers use it to decode `message`
+   * back into bytes when reconstructing the signed blob for verification.
+   */
+  encoding?: 'utf-8' | 'base64';
+  /**
+   * CAIP-2 chain identifier that was embedded in the signed blob. Enables
+   * third-party verifiers to reconstruct the exact signed bytes without
+   * extra network context.
+   */
+  caipChainId?: string;
+  /**
+   * Decoded message byte length (NOT character count). Prevents truncation
+   * ambiguity when verifying the signature.
+   */
+  messageLength?: number;
+  /** Additional metadata from the wallet. */
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Abstract base class that all wallet providers must implement.
+ *
+ * @description
+ * BaseWalletProvider defines the contract for wallet integrations. All providers
+ * (HSuite Native, WalletConnect, P2P, etc.) extend this class to ensure a
+ * consistent API for dApp developers.
+ *
+ * Key responsibilities:
+ * - Managing connection state via reactive signals
+ * - Exposing connected accounts
+ * - Handling transaction signing and submission
+ * - Message signing for authentication
+ *
+ * Implementers must provide:
+ * - Unique `id` and `metadata` for identification
+ * - Reactive `status`, `accounts`, and `error` signals
+ * - `connect()` and `disconnect()` lifecycle methods
+ * - `signTransaction()`, `submitTransaction()`, and `signMessage()` for operations
+ * - `isAvailable()` to check if the wallet type is available
+ *
+ * @publicApi
+ */
+export abstract class BaseWalletProvider {
+  /**
+   * Unique identifier for this provider instance.
+   *
+   * @description
+   * Used to identify the provider in the registry. Must be unique across
+   * all registered providers.
+   */
+  abstract readonly id: string;
+
+  /**
+   * Provider metadata for display and identification.
+   *
+   * @description
+   * Contains display information (name, description, icon) and feature flags
+   * for the provider.
+   */
+  abstract readonly metadata: ProviderMetadata;
+
+  /**
+   * Current connection status as a reactive Angular signal.
+   *
+   * @description
+   * Tracks the lifecycle state of the wallet connection. UI components can
+   * use this signal to reactively update based on connection state.
+   *
+   * Possible values:
+   * - `'idle'`: Not connected, no connection attempt in progress
+   * - `'connecting'`: Connection attempt in progress
+   * - `'connected'`: Successfully connected to wallet
+   * - `'disconnected'`: Previously connected, now disconnected
+   * - `'error'`: Connection failed (check `error` signal for details)
+   */
+  abstract readonly status: Signal<ConnectionStatus>;
+
+  /**
+   * Connected accounts as a reactive Angular signal.
+   *
+   * @description
+   * List of accounts available from the connected wallet. Empty when
+   * disconnected. Updates automatically when wallet accounts change.
+   */
+  abstract readonly accounts: Signal<UnifiedAccount[]>;
+
+  /**
+   * Error message if status is 'error', as a reactive Angular signal.
+   *
+   * @description
+   * Contains human-readable error message when connection fails.
+   * Null when no error has occurred.
+   */
+  abstract readonly error: Signal<string | null>;
+
+  /**
+   * Connects to the wallet with the given configuration.
+   *
+   * @description
+   * Initiates a connection to the wallet. The connection flow varies by
+   * provider type (QR code, popup, deep link, etc.).
+   *
+   * @param config - Provider-specific connection configuration
+   *
+   * @throws {Error} If connection fails or times out
+   */
+  abstract connect(config: ConnectionConfig): Promise<void>;
+
+  /**
+   * Disconnects from the wallet.
+   *
+   * @description
+   * Terminates the wallet connection and clears account state.
+   */
+  abstract disconnect(): Promise<void>;
+
+  /**
+   * Signs a transaction without submitting it.
+   *
+   * @description
+   * Requests the wallet to sign the transaction payload. The signed
+   * transaction can later be submitted to the network.
+   *
+   * @param options - Transaction signing options
+   *
+   * @returns Promise resolving to the signing result
+   *
+   * @throws {Error} If user rejects or signing fails
+   */
+  abstract signTransaction(options: SignTransactionOptions): Promise<SignResult>;
+
+  /**
+   * Signs and submits a transaction to the network.
+   *
+   * @description
+   * Performs a complete transaction lifecycle: sign and submit to the
+   * blockchain network.
+   *
+   * @param options - Transaction submission options
+   *
+   * @returns Promise resolving to the submission result
+   *
+   * @throws {Error} If user rejects, signing fails, or submission fails
+   */
+  abstract submitTransaction(options: SubmitTransactionOptions): Promise<SubmitResult>;
+
+  /**
+   * Signs an arbitrary message.
+   *
+   * @description
+   * Requests the wallet to sign a non-transaction message, typically used
+   * for authentication challenges, DAO voting, or proof-of-ownership.
+   *
+   * @param options - Message signing options
+   *
+   * @returns Promise resolving to the signature result
+   *
+   * @throws {Error} If user rejects or signing fails
+   */
+  abstract signMessage(options: SignMessageOptions): Promise<SignMessageResult>;
+
+  /**
+   * Checks if this provider is available in the current environment.
+   *
+   * @description
+   * Determines if the wallet type can be used. For example:
+   * - Browser extension providers check if the extension is installed
+   * - WebRTC providers check for RTCPeerConnection support
+   * - Native providers typically return true
+   *
+   * @returns Promise resolving to true if provider can be used
+   */
+  abstract isAvailable(): Promise<boolean>;
+
+  /**
+   * Gets the primary (first) connected account.
+   *
+   * @description
+   * Convenience method to retrieve the first account from the connected
+   * wallet. Returns null if no accounts are connected.
+   *
+   * @returns The first connected account, or null if none
+   */
+  getPrimaryAccount(): UnifiedAccount | null {
+    const accts = this.accounts();
+    return accts.length > 0 ? accts[0] : null;
+  }
+
+  /**
+   * Checks if the provider is currently connected.
+   *
+   * @description
+   * Convenience method that checks if `status()` equals `'connected'`.
+   *
+   * @returns true if provider is connected, false otherwise
+   */
+  isConnected(): boolean {
+    return this.status() === 'connected';
+  }
+}

package/src/lib/providers/hsuite-native/channel-client.service.spec.ts

@@ -0,0 +1,73 @@
+/**
+ * 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
+ */
+
+/**
+ * @fileoverview Regression tests for the default wallet URL used when a
+ * consuming dApp connects without supplying its own `walletUrl`.
+ *
+ * Guards against the regression where the SDK opened the wallet on
+ * `http://localhost:8100` (a dev value) instead of the production wallet,
+ * causing dApps in production to point users at localhost.
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest';
+import { TestBed } from '@angular/core/testing';
+import type { ChannelInvite } from '@hsuite/native-connect-sdk';
+import { ChannelClientService } from './channel-client.service';
+import { DEFAULT_WALLET_URL } from '../../models/provider-types';
+
+/** Minimal, valid session invite sufficient for invite-URL generation. */
+function makeInvite(): ChannelInvite {
+  return {
+    v: 2,
+    id: 'test-channel-id',
+    type: 'session',
+    key: 'dGVzdC1lbmNyeXB0aW9uLWtleQ',
+    relays: ['wss://nostr.hsuite.network'],
+    app: { id: 'test-dapp', name: 'Test dApp' },
+    context: { ledgerId: 'hedera', networkId: 'testnet' },
+  };
+}
+
+describe('wallet URL default (regression: dApp opened wallet on localhost)', () => {
+  describe('DEFAULT_WALLET_URL', () => {
+    it('points at the production wallet origin', () => {
+      expect(DEFAULT_WALLET_URL).toBe('https://wallet.hsuite.app');
+    });
+
+    it('is a production-safe https origin, never localhost', () => {
+      const url = new URL(DEFAULT_WALLET_URL);
+      expect(url.protocol).toBe('https:');
+      expect(url.hostname).toBe('wallet.hsuite.app');
+      expect(DEFAULT_WALLET_URL).not.toMatch(/localhost|127\.0\.0\.1/);
+    });
+  });
+
+  describe('ChannelClientService.getWalletInviteUrl', () => {
+    let service: ChannelClientService;
+
+    beforeEach(() => {
+      TestBed.configureTestingModule({});
+      service = TestBed.inject(ChannelClientService);
+    });
+
+    it('defaults to the production wallet origin when no walletUrl is given', () => {
+      const url = service.getWalletInviteUrl(makeInvite());
+      expect(new URL(url).origin).toBe('https://wallet.hsuite.app');
+      expect(url).not.toMatch(/localhost|wallet\.hsuite\.network/);
+      expect(url).toContain('?hsuite_invite=');
+    });
+
+    it('still honors an explicit walletUrl (e.g. a local dev server)', () => {
+      const url = service.getWalletInviteUrl(makeInvite(), 'http://localhost:8100');
+      expect(new URL(url).origin).toBe('http://localhost:8100');
+    });
+  });
+});