@hsuite/native-connect-angular 1.0.0 → 2.1.1

package/src/lib/services/smart-session.service.ts

@@ -0,0 +1,378 @@
+/**
+ * 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 Smart-host customer session helper.
+ *
+ * @module services/smart-session
+ *
+ * @description
+ * SmartSessionService automates the smart-host authentication handshake for
+ * HSuite dApps. It discovers the host's `appId`, requests a challenge, signs it
+ * with the active wallet account, and exchanges the signed challenge for a
+ * short-lived bearer token.
+ *
+ * **Typical flow:**
+ * ```typescript
+ * const session = inject(SmartSessionService);
+ * await session.login();
+ * const bearer = session.getBearer();
+ * ```
+ *
+ * The service also exposes {@link withSession} for automatic 401 recovery:
+ * operations that fail with HTTP 401 are retried once after a fresh login.
+ */
+
+import { HttpClient } from '@angular/common/http';
+import { Injectable, inject, InjectionToken } from '@angular/core';
+import { getLogger } from '@hsuite/native-connect-sdk';
+import { firstValueFrom } from 'rxjs';
+
+import type { SignMessageResult } from '../providers/base-wallet-provider';
+
+import { TransactionService } from './transaction.service';
+import { UnifiedWalletService } from './unified-wallet.service';
+
+const logger = getLogger().scoped?.('SmartSessionService') ?? getLogger();
+
+/**
+ * Configuration token for {@link SmartSessionService}.
+ */
+export const SMART_SESSION_CONFIG = new InjectionToken<SmartSessionConfig>('SMART_SESSION_CONFIG', {
+  factory: () => ({}),
+});
+
+/**
+ * Configuration for the smart-host session handshake.
+ */
+export interface SmartSessionConfig {
+  /**
+   * Base URL for the smart-host API.
+   * @default '' (relative to the current origin)
+   */
+  baseUrl?: string;
+
+  /**
+   * Health endpoint used to discover the host `appId`.
+   * @default '/api/health'
+   */
+  healthEndpoint?: string;
+
+  /**
+   * Challenge endpoint used to obtain a message to sign.
+   * @default '/api/auth/challenge'
+   */
+  challengeEndpoint?: string;
+
+  /**
+   * Verify endpoint used to exchange the signed challenge for a bearer token.
+   * @default '/api/auth/verify'
+   */
+  verifyEndpoint?: string;
+
+  /**
+   * sessionStorage key used to persist the session token and expiry.
+   * @default 'hsuite.smart-session'
+   */
+  storageKey?: string;
+}
+
+/**
+ * Health response shape expected from the smart host.
+ */
+export interface SmartHostHealth {
+  appId: string;
+  [key: string]: unknown;
+}
+
+/**
+ * Challenge response shape expected from the smart host.
+ */
+export interface SmartHostChallenge {
+  challenge: string;
+  [key: string]: unknown;
+}
+
+/**
+ * Verify request payload sent to the smart host.
+ */
+export interface SmartHostVerifyRequest {
+  appId: string;
+  accountAddress: string;
+  publicKey?: string;
+  signature: string;
+  algorithm?: string;
+  message: string;
+  caipChainId?: string;
+  ledgerId?: string;
+  networkId?: string;
+}
+
+/**
+ * Verify response shape expected from the smart host.
+ */
+export interface SmartHostVerifyResponse {
+  bearer: string;
+  expiresAt?: number;
+  expiresIn?: number;
+  [key: string]: unknown;
+}
+
+/**
+ * Persisted smart session.
+ */
+interface StoredSession {
+  bearer: string;
+  expiresAt: number;
+}
+
+/**
+ * Smart-host customer session helper.
+ *
+ * @service SmartSessionService
+ *
+ * @description
+ * Encapsulates the full challenge → sign → verify → store JWT flow required by
+ * HSuite smart hosts. The service is intentionally thin: it delegates signing to
+ * {@link TransactionService} and relies on standard Angular `HttpClient` for the
+ * host HTTP calls.
+ *
+ * @providedIn root
+ */
+@Injectable({ providedIn: 'root' })
+export class SmartSessionService {
+  private readonly http = inject(HttpClient);
+  private readonly walletService = inject(UnifiedWalletService);
+  private readonly transactionService = inject(TransactionService);
+  private readonly config = inject(SMART_SESSION_CONFIG);
+
+  private get baseUrl(): string {
+    return this.config.baseUrl ?? '';
+  }
+
+  private get healthEndpoint(): string {
+    return this.config.healthEndpoint ?? '/api/health';
+  }
+
+  private get challengeEndpoint(): string {
+    return this.config.challengeEndpoint ?? '/api/auth/challenge';
+  }
+
+  private get verifyEndpoint(): string {
+    return this.config.verifyEndpoint ?? '/api/auth/verify';
+  }
+
+  private get storageKey(): string {
+    return this.config.storageKey ?? 'hsuite.smart-session';
+  }
+
+  /**
+   * Returns the currently stored bearer token, or `null` if there is no session.
+   *
+   * @returns Bearer token string or null
+   */
+  getBearer(): string | null {
+    const stored = this.readStoredSession();
+    return stored && stored.expiresAt > Date.now() ? stored.bearer : null;
+  }
+
+  /**
+   * Checks whether a non-expired session is available.
+   *
+   * @returns true if logged in and the bearer has not expired
+   */
+  isLoggedIn(): boolean {
+    return this.getBearer() !== null;
+  }
+
+  /**
+   * Performs the full smart-host login handshake.
+   *
+   * @description
+   * 1. Discovers `appId` from the health endpoint.
+   * 2. Fetches a challenge from the challenge endpoint.
+   * 3. Signs the challenge with the active wallet account.
+   * 4. Exchanges the signed challenge for a bearer token.
+   * 5. Stores the bearer and expiry in `sessionStorage`.
+   *
+   * @returns The verify response from the host
+   *
+   * @throws {Error} If no active account is available
+   * @throws {Error} If the health endpoint does not return an `appId`
+   * @throws {Error} If the challenge endpoint does not return a `challenge`
+   * @throws {Error} If the verify call fails
+   */
+  async login(): Promise<SmartHostVerifyResponse> {
+    const account = this.walletService.activeAccount();
+    if (!account) {
+      throw new Error('No active account');
+    }
+
+    logger.info('Starting smart-host login handshake', {
+      accountAddress: account.address,
+    });
+
+    const health = await this.fetchHealth();
+    if (!health.appId) {
+      throw new Error('Smart host health endpoint did not return appId');
+    }
+
+    const challengeResponse = await this.fetchChallenge(health.appId);
+    if (!challengeResponse.challenge) {
+      throw new Error('Smart host challenge endpoint did not return challenge');
+    }
+
+    const signResult = await this.transactionService.signMessage(challengeResponse.challenge);
+
+    const verifyResponse = await this.verifyChallenge(
+      health.appId,
+      account,
+      challengeResponse.challenge,
+      signResult,
+    );
+
+    if (!verifyResponse.bearer) {
+      throw new Error('Smart host verify endpoint did not return bearer');
+    }
+
+    const expiresAt = this.resolveExpiry(verifyResponse);
+    this.storeSession({ bearer: verifyResponse.bearer, expiresAt });
+
+    logger.info('Smart-host login successful', {
+      appId: health.appId,
+      expiresAt,
+    });
+
+    return verifyResponse;
+  }
+
+  /**
+   * Clears the stored session.
+   */
+  logout(): void {
+    this.clearStoredSession();
+    logger.info('Smart-host session cleared');
+  }
+
+  /**
+   * Runs an HTTP operation with automatic 401 recovery.
+   *
+   * @description
+   * Executes the provided operation. If it rejects with an HTTP 401 error,
+   * the service clears the current bearer, performs a fresh login, and retries
+   * the operation once. Any other error is propagated immediately.
+   *
+   * @param operation - Async operation that needs a valid session
+   * @returns The result of the operation
+   *
+   * @throws {Error} The original error if retry is not possible or fails
+   */
+  async withSession<T>(operation: () => Promise<T>): Promise<T> {
+    try {
+      return await operation();
+    } catch (error) {
+      if (this.isUnauthorizedError(error)) {
+        logger.warn('Operation received 401; attempting single session refresh');
+        this.logout();
+        await this.login();
+        return await operation();
+      }
+      throw error;
+    }
+  }
+
+  private async fetchHealth(): Promise<SmartHostHealth> {
+    return firstValueFrom(this.http.get<SmartHostHealth>(`${this.baseUrl}${this.healthEndpoint}`));
+  }
+
+  private async fetchChallenge(appId: string): Promise<SmartHostChallenge> {
+    return firstValueFrom(
+      this.http.post<SmartHostChallenge>(`${this.baseUrl}${this.challengeEndpoint}`, { appId }),
+    );
+  }
+
+  private async verifyChallenge(
+    appId: string,
+    account: import('../models/unified-account.model').UnifiedAccount,
+    challenge: string,
+    signResult: SignMessageResult,
+  ): Promise<SmartHostVerifyResponse> {
+    const payload: SmartHostVerifyRequest = {
+      appId,
+      accountAddress: account.address,
+      publicKey: signResult.publicKey ?? account.publicKey,
+      signature: signResult.signature,
+      algorithm: signResult.algorithm,
+      message: challenge,
+      caipChainId: signResult.caipChainId,
+      ledgerId: account.ledgerId,
+      networkId: account.networkId,
+    };
+
+    return firstValueFrom(
+      this.http.post<SmartHostVerifyResponse>(`${this.baseUrl}${this.verifyEndpoint}`, payload),
+    );
+  }
+
+  private resolveExpiry(response: SmartHostVerifyResponse): number {
+    if (response.expiresAt) {
+      return response.expiresAt;
+    }
+    if (response.expiresIn) {
+      return Date.now() + response.expiresIn * 1000;
+    }
+    // Default to 5 minutes if no expiry is provided
+    return Date.now() + 5 * 60 * 1000;
+  }
+
+  private readStoredSession(): StoredSession | null {
+    try {
+      const raw = sessionStorage.getItem(this.storageKey);
+      if (!raw) {
+        return null;
+      }
+      const parsed = JSON.parse(raw) as StoredSession;
+      if (!parsed.bearer || typeof parsed.expiresAt !== 'number') {
+        return null;
+      }
+      return parsed;
+    } catch {
+      return null;
+    }
+  }
+
+  private storeSession(session: StoredSession): void {
+    try {
+      sessionStorage.setItem(this.storageKey, JSON.stringify(session));
+    } catch (error) {
+      logger.warn('Failed to store smart session', { error });
+    }
+  }
+
+  private clearStoredSession(): void {
+    try {
+      sessionStorage.removeItem(this.storageKey);
+    } catch (error) {
+      logger.warn('Failed to clear smart session', { error });
+    }
+  }
+
+  private isUnauthorizedError(error: unknown): boolean {
+    if (!error || typeof error !== 'object') {
+      return false;
+    }
+    const status = (error as { status?: number }).status;
+    if (typeof status === 'number') {
+      return status === 401;
+    }
+    const message = String((error as { message?: unknown }).message ?? '');
+    return /\b401\b|unauthorized/i.test(message);
+  }
+}

package/src/lib/services/transaction-builders/active-account-source.spec.ts

@@ -0,0 +1,75 @@
+/**
+ * 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 #5 decoupling. The Hedera transaction builder must resolve the
+ * active account through the ACTIVE_ACCOUNT_SOURCE token, NOT by injecting
+ * UnifiedWalletService directly. A default root provider keeps the token
+ * pointing at UnifiedWalletService, so existing SDK consumers are unaffected
+ * (the comprehensive hedera-transaction-builder.service.spec, which provides a
+ * UnifiedWalletService mock, is the backward-compatibility proof). The embedded
+ * shell overrides the token with a one-member account context, which is why the
+ * stub-of-UnifiedWalletService and its Proxy guard can be deleted.
+ */
+
+import { TestBed } from '@angular/core/testing';
+import { describe, it, expect } from 'vitest';
+import { signal } from '@angular/core';
+
+import { HederaTransactionBuilderService } from './hedera-transaction-builder.service';
+import { ACTIVE_ACCOUNT_SOURCE, type ActiveAccountSource } from './active-account-source';
+import { LoggerService } from '../logger.service';
+import { UnifiedWalletService } from '../unified-wallet.service';
+import type { UnifiedAccount } from '../../models/unified-account.model';
+
+const mockLogger = {
+  scoped: () => ({ debug() {}, info() {}, warn() {}, error() {} }),
+};
+
+function testnetSource(networkId = 'hedera:testnet'): ActiveAccountSource {
+  const account: UnifiedAccount = {
+    id: `embedded:hedera:${networkId}:0.0.2193470`,
+    address: '0.0.2193470',
+    ledgerId: 'hedera',
+    networkId,
+    providerId: 'test',
+    providerType: 'hsuite-native',
+    metadata: {},
+  };
+  return { activeAccount: signal<UnifiedAccount | null>(account) };
+}
+
+describe('ACTIVE_ACCOUNT_SOURCE (Hedera builder decoupling, #5)', () => {
+  it('builds a Hedera transaction from ACTIVE_ACCOUNT_SOURCE with NO UnifiedWalletService provided', async () => {
+    TestBed.configureTestingModule({
+      providers: [
+        { provide: ACTIVE_ACCOUNT_SOURCE, useValue: testnetSource() },
+        { provide: LoggerService, useValue: mockLogger },
+        // UnifiedWalletService is deliberately NOT provided: the builder must
+        // resolve its network purely from the account source.
+      ],
+    });
+
+    const builder = TestBed.inject(HederaTransactionBuilderService);
+    const payload = await builder.buildSendHbar('0.0.123', '0.0.456', 1);
+
+    expect(typeof payload).toBe('string');
+    expect(payload.length).toBeGreaterThan(0);
+  });
+
+  it('default provider falls back to UnifiedWalletService (backward compatible)', () => {
+    const fakeUnified = { activeAccount: signal<UnifiedAccount | null>(null) };
+    TestBed.configureTestingModule({
+      providers: [{ provide: UnifiedWalletService, useValue: fakeUnified }],
+    });
+
+    expect(TestBed.inject(ACTIVE_ACCOUNT_SOURCE)).toBe(fakeUnified);
+  });
+});

package/src/lib/services/transaction-builders/active-account-source.ts

@@ -0,0 +1,55 @@
+/**
+ * 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 ACTIVE_ACCOUNT_SOURCE: the minimal active-account read surface the
+ * transaction builders need.
+ *
+ * @description
+ * The Hedera transaction builder only reads `activeAccount()` from the wallet
+ * (to pick the network and the entity key config). Injecting the whole
+ * {@link UnifiedWalletService} couples the builder to a heavy root service that
+ * also runs the dApp connect stack on construction. This token narrows that
+ * dependency to a single member.
+ *
+ * The default provider points at {@link UnifiedWalletService}, so existing SDK
+ * consumers that already provide it need NO wiring change (backward
+ * compatible). The embedded widget shell overrides this token with a one-member
+ * account context, which keeps the heavy root service from ever being
+ * constructed inside the wallet.
+ */
+
+import { InjectionToken, inject, type Signal } from '@angular/core';
+
+import type { UnifiedAccount } from '../../models/unified-account.model';
+import { UnifiedWalletService } from '../unified-wallet.service';
+
+/**
+ * The only member the transaction builders read from the active wallet account.
+ * Implemented by {@link UnifiedWalletService} (the default) and by the embedded
+ * shell's one-member account context.
+ */
+export interface ActiveAccountSource {
+  readonly activeAccount: Signal<UnifiedAccount | null>;
+}
+
+/**
+ * Injection token for the active-account read surface. Defaults to
+ * {@link UnifiedWalletService} so consumers that already provide it need no
+ * extra wiring; override it to supply a narrower source (the embedded shell
+ * does this to avoid constructing the root service inside the wallet).
+ */
+export const ACTIVE_ACCOUNT_SOURCE = new InjectionToken<ActiveAccountSource>(
+  'ACTIVE_ACCOUNT_SOURCE',
+  {
+    providedIn: 'root',
+    factory: () => inject(UnifiedWalletService),
+  },
+);

package/src/lib/services/transaction-builders/hedera-transaction-builder.service.ts

@@ -69,8 +69,8 @@ import {
 } from '@hashgraph/sdk';
 
 import { LoggerService } from '../logger.service';
-import { UnifiedWalletService } from '../unified-wallet.service';
 
+import { ACTIVE_ACCOUNT_SOURCE } from './active-account-source';
 import { scaleHederaAmountToBaseUnits, assertSafeInteger } from './hedera-amount-utils';
 
 /**
@@ -270,7 +270,7 @@ export interface AccountCreateOptions {
   providedIn: 'root',
 })
 export class HederaTransactionBuilderService {
-  private readonly wallet = inject(UnifiedWalletService);
+  private readonly accountSource = inject(ACTIVE_ACCOUNT_SOURCE);
   private readonly logger = inject(LoggerService).scoped('HederaTransactionBuilder');
 
   /**
@@ -286,7 +286,7 @@ export class HederaTransactionBuilderService {
    * @throws {Error} When used in methods that require a network, if no account is active
    */
   private getNetworkId(): string | undefined {
-    const activeAccount = this.wallet.activeAccount();
+    const activeAccount = this.accountSource.activeAccount();
     return activeAccount?.networkId;
   }
 
@@ -337,7 +337,7 @@ export class HederaTransactionBuilderService {
    * @returns Key configuration or undefined if no active account
    */
   private getActiveAccountKeyConfig(): HederaKeyConfig | undefined {
-    const activeAccount = this.wallet.activeAccount();
+    const activeAccount = this.accountSource.activeAccount();
     if (!activeAccount) {
       this.logger.debug('No active account for key config');
       return undefined;

package/src/lib/services/transaction-builders/index.ts

@@ -52,3 +52,4 @@ export {
 } from './hedera-transaction-builder.service';
 export { XrplTransactionBuilderService } from './xrpl-transaction-builder.service';
 export { scaleHederaAmountToBaseUnits, assertSafeInteger } from './hedera-amount-utils';
+export { ACTIVE_ACCOUNT_SOURCE, type ActiveAccountSource } from './active-account-source';

package/src/lib/services/transaction.service.ts

@@ -52,12 +52,15 @@ import { Injectable, inject, signal, type Signal, type WritableSignal } from '@a
 import { getLogger } from '@hsuite/native-connect-sdk';
 import { ToastController } from '@ionic/angular/standalone';
 
-import type { SignResult, SubmitResult } from '../providers/base-wallet-provider';
+import type {
+  SignMessageResult,
+  SignResult,
+  SubmitResult,
+} from '../providers/base-wallet-provider';
 
 import { UnifiedWalletService } from './unified-wallet.service';
 import { WalletEventBus } from './wallet-event-bus.service';
 
-
 const logger = getLogger().scoped?.('TransactionService') ?? getLogger();
 
 /**
@@ -211,9 +214,9 @@ export class TransactionService {
    * @param message - Message to sign
    * @returns Sign result with signature
    */
-  async signMessage(message: string): Promise<SignResult> {
+  async signMessage(message: string): Promise<SignMessageResult> {
     return this.executeTransaction(async () => {
-      const result = (await this.walletService.signMessage(message)) as SignResult;
+      const result = await this.walletService.signMessage(message);
       logger.info('Message signed', { hasSignature: !!result.signature });
       await this.showSuccessToast('Message Signed', 'Your message has been signed successfully.');
       return result;

package/src/lib/services/unified-wallet.service.spec.ts

@@ -409,7 +409,7 @@ class TestableUnifiedWalletService {
     });
   }
 
-  async signMessage(message: string, encoding?: 'utf-8' | 'base64'): Promise<unknown> {
+  async signMessage(message: string, encoding?: 'utf-8' | 'base64'): Promise<SignMessageResult> {
     const account = this._activeAccount();
     if (!account) {
       throw new Error('No active account');

package/src/lib/services/unified-wallet.service.ts

@@ -49,14 +49,13 @@ import { getLogger } from '@hsuite/native-connect-sdk';
 import type { ConnectionConfig } from '../models/connection-config.model';
 import type { ProviderType, ConnectionStatus } from '../models/provider-types';
 import type { UnifiedAccount } from '../models/unified-account.model';
-import { BaseWalletProvider } from '../providers/base-wallet-provider';
+import { BaseWalletProvider, SignMessageResult } from '../providers/base-wallet-provider';
 import { HsuiteNativeProvider } from '../providers/hsuite-native-provider';
 import { P2PNativeProvider } from '../providers/p2p-native/p2p-native.provider';
 import { WalletConnectV2Provider } from '../providers/walletconnect/core/walletconnect-provider';
 
 import { WalletEventBus } from './wallet-event-bus.service';
 
-
 const logger = getLogger().scoped?.('UnifiedWalletService') ?? getLogger();
 
 interface ProviderSummary {
@@ -564,7 +563,7 @@ export class UnifiedWalletService {
    * @throws {Error} If provider is not found
    * @throws {Error} If user rejects the signing request
    */
-  async signMessage(message: string, encoding?: 'utf-8' | 'base64'): Promise<unknown> {
+  async signMessage(message: string, encoding?: 'utf-8' | 'base64'): Promise<SignMessageResult> {
     const account = this._activeAccount();
     if (!account) {
       throw new Error('No active account');

package/src/lib/services/wallet-providers.service.ts

@@ -44,7 +44,6 @@ import { WalletConnectV2Provider } from '../providers/walletconnect/core/walletc
 
 import { UnifiedWalletService } from './unified-wallet.service';
 
-
 const logger = getLogger().scoped?.('WalletProvidersService') ?? getLogger();
 
 /**

package/src/lib/utils/index.ts

@@ -11,4 +11,5 @@
 /**
  * Utility exports for @hsuite/native-connect-angular
  */
+export * from './ledger-ui-registry';
 export * from './ledger-icons.util';