@hsuite/native-connect-angular 1.0.0

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

@@ -0,0 +1,862 @@
+/**
+ * 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 channel-client.service.ts
+ * @description Angular wrapper for the unified ChannelClient.
+ *
+ * ChannelClientService
+ *
+ * Angular service that wraps the ChannelClient from native-wallet-sdk,
+ * providing reactive signals and Angular-friendly APIs for dApp-wallet
+ * communication using the new unified channel protocol.
+ *
+ * Key features:
+ * - Reactive state via Angular signals
+ * - NgZone integration for proper change detection
+ * - Automatic session persistence
+ * - Support for both session (1:1) and party (N:N) channels
+ *
+ * This service is designed to replace the existing NostrSessionClient
+ * as part of the protocol simplification effort. It can coexist with
+ * the legacy implementation during migration.
+ *
+ * @Component({ ... })
+ * export class AppComponent {
+ *   private channelService = inject(ChannelClientService);
+ *
+ *   readonly state = this.channelService.state;
+ *   readonly accounts = this.channelService.accounts;
+ *
+ *   async connect() {
+ *     const invite = await this.channelService.connect({
+ *       type: 'session',
+ *       appId: 'my-dapp',
+ *       appName: 'My dApp',
+ *       ledgerId: 'hedera',
+ *       networkId: 'mainnet',
+ *     });
+ *     // Open wallet with invite URL
+ *     window.open(this.channelService.getWalletInviteUrl(invite, walletUrl));
+ *   }
+ * }
+ * ```
+ */
+
+import {
+  Injectable,
+  inject,
+  signal,
+  computed,
+  NgZone,
+  type Signal,
+  type WritableSignal,
+} from '@angular/core';
+import {
+  ChannelClient,
+  type ChannelInvite,
+  type ChannelState,
+  type ChannelType,
+  type ChannelAccount,
+  type TransportState,
+  type PersistedChannel,
+  encodeChannelInvite,
+  getLogger,
+} from '@hsuite/native-connect-sdk';
+
+import { DEFAULT_WALLET_URL } from '../../models/provider-types';
+import type { UnifiedAccount } from '../../models/unified-account.model';
+
+const logger = getLogger().scoped?.('ChannelClientService') ?? getLogger();
+
+/**
+ * ChannelConnectConfig
+ *
+ * Configuration for establishing a new channel.
+ */
+export interface ChannelConnectConfig {
+  /** Channel type: 'session' for 1:1, 'party' for multisig */
+  type: ChannelType;
+  /** dApp identifier */
+  appId: string;
+  /** dApp display name */
+  appName: string;
+  /** dApp icon URL (optional) */
+  appIcon?: string;
+  /**
+   * dApp origin URL (optional). When omitted, the SDK falls back to
+   * `window.location.origin` so the wallet can always show the user where the
+   * connection request is coming from. Override this only if your dApp serves
+   * the wallet integration from a different origin than the page hosting it.
+   */
+  appOrigin?: string;
+  /** Target ledger (e.g., 'hedera', 'xrpl') */
+  ledgerId: string;
+  /** Target network (e.g., 'mainnet', 'testnet') */
+  networkId: string;
+  /** Requested permissions */
+  permissions?: string[];
+  /** Nostr relay URLs (optional, uses defaults) */
+  relays?: string[];
+  /** Wallet URL for generating invite links */
+  walletUrl?: string;
+}
+
+/**
+ * ChannelClientService
+ *
+ * Angular service for unified channel-based dApp-wallet communication.
+ */
+@Injectable({ providedIn: 'root' })
+export class ChannelClientService {
+  private readonly zone = inject(NgZone);
+  private client: ChannelClient | null = null;
+
+  // ============================================================================
+  // Reactive State
+  // ============================================================================
+
+  /** Current channel state */
+  private readonly _state: WritableSignal<ChannelState> = signal('idle');
+  readonly state: Signal<ChannelState> = this._state.asReadonly();
+
+  /** Current transport state (nostr-only, p2p-connected, etc.) */
+  private readonly _transportState: WritableSignal<TransportState> = signal('nostr-only');
+  readonly transportState: Signal<TransportState> = this._transportState.asReadonly();
+
+  /** Approved accounts from the wallet */
+  private readonly _accounts: WritableSignal<ChannelAccount[]> = signal([]);
+  readonly accounts: Signal<ChannelAccount[]> = this._accounts.asReadonly();
+
+  /** Current channel invite (if connected) */
+  private readonly _currentInvite: WritableSignal<ChannelInvite | null> = signal(null);
+  readonly currentInvite: Signal<ChannelInvite | null> = this._currentInvite.asReadonly();
+
+  /** Error message (if any) */
+  private readonly _error: WritableSignal<string | null> = signal(null);
+  readonly error: Signal<string | null> = this._error.asReadonly();
+
+  /** Flag to prevent auto-restore from interfering with new connections */
+  private connectingNewSession = false;
+
+  // ============================================================================
+  // Computed State
+  // ============================================================================
+
+  /** Whether the channel is currently connected and active */
+  readonly isConnected = computed(() => this._state() === 'active');
+
+  /** Whether we're currently connecting */
+  readonly isConnecting = computed(() => {
+    const s = this._state();
+    return s === 'connecting' || s === 'pending';
+  });
+
+  /** Accounts formatted as UnifiedAccount for compatibility */
+  readonly unifiedAccounts = computed<UnifiedAccount[]>(() => {
+    const accounts = this._accounts();
+    const invite = this._currentInvite();
+    if (!invite) return [];
+
+    return accounts.map((account, index) => {
+      const accountMetadata = (account as { metadata?: Record<string, unknown> }).metadata;
+      return {
+        id: `channel-${account.address}`,
+        address: account.address,
+        label: account.alias ?? `Account ${index + 1}`,
+        ledgerId: account.ledgerId,
+        networkId: account.networkId,
+        providerId: 'hsuite-native',
+        providerType: 'hsuite-native' as const,
+        metadata: {
+          ...(accountMetadata ?? {}),
+          channelId: invite.id,
+          channelType: invite.type,
+          isMultisig: account.isMultisig === true,
+          multisigThreshold: account.multisigThreshold,
+          multisigTotal: account.multisigTotal,
+          publicKey: account.publicKey ?? '',
+        },
+      };
+    });
+  });
+
+  /**
+   *
+   */
+  constructor() {
+    // Note: Auto-restore is intentionally NOT called here.
+    // Session lifecycle (connect/disconnect/restore) is controlled by
+    // HsuiteNativeProvider, which calls attemptRestore() as needed.
+    // This keeps ChannelClientService as a passive wrapper.
+  }
+
+  // ============================================================================
+  // Public API
+  // ============================================================================
+
+  /**
+   * Establish a new channel connection.
+   * Returns the invite to share with the wallet (via QR code or deep link).
+   *
+   * @param config - Channel configuration
+   * @returns The channel invite for wallet scanning
+   */
+  async connect(config: ChannelConnectConfig): Promise<ChannelInvite> {
+    if (this._state() === 'connecting' || this._state() === 'pending') {
+      logger.warn('Connection already in progress');
+      const existing = this._currentInvite();
+      if (existing) return existing;
+      throw new Error('Connection already in progress');
+    }
+
+    // Mark that we're initiating a new session to prevent auto-restore interference
+    this.connectingNewSession = true;
+
+    // CRITICAL: Disconnect any existing client before creating a new one
+    // This prevents the old client from interfering with the new connection
+    if (this.client) {
+      try {
+        await this.client.disconnect();
+      } catch {
+        // Ignore disconnect errors
+      }
+      this.client = null;
+    }
+
+    // Clear any old stored session before starting a new connection
+    // This prevents restoration of old sessions during the connection process
+    this.clearStoredChannel();
+
+    this.runInZone(() => {
+      this._state.set('connecting');
+      this._error.set(null);
+      this._currentInvite.set(null);
+      this._accounts.set([]);
+    });
+
+    try {
+      // Create new client with callbacks for immediate state updates
+      // This ensures rejection/disconnection is detected immediately, not just via polling
+      this.client = new ChannelClient({
+        onStateChange: (state) => {
+          // Log immediately before runInZone for debugging
+          console.log('[ChannelClientService] onStateChange callback received:', {
+            newState: state,
+            previousState: this._state(),
+            timestamp: Date.now(),
+          });
+
+          this.runInZone(() => {
+            const previousState = this._state();
+            if (state !== previousState) {
+              logger.debug('State change via callback', { from: previousState, to: state });
+              this._state.set(state);
+
+              // Handle error state - this is triggered on rejection
+              if (state === 'error') {
+                console.log(
+                  '[ChannelClientService] Error state detected - connection rejected or failed',
+                );
+                const errorMsg = 'Connection rejected or failed';
+                this._error.set(errorMsg);
+              }
+
+              // Handle disconnected state explicitly
+              if (state === 'disconnected') {
+                console.log('[ChannelClientService] Disconnected state detected');
+              }
+
+              // Reset connecting flag when connection is complete or failed
+              if (state === 'active' || state === 'error' || state === 'disconnected') {
+                this.connectingNewSession = false;
+              }
+
+              // Persist when active
+              if (state === 'active' && previousState !== 'active') {
+                this.persistCurrentState();
+              }
+            }
+          });
+        },
+        onAccountsChange: (accounts) => {
+          this.runInZone(() => {
+            logger.debug('Accounts change via callback', { count: accounts.length });
+            this._accounts.set(accounts);
+            // Re-persist when accounts change
+            if (this._state() === 'active') {
+              this.persistCurrentState();
+            }
+          });
+        },
+        onTransportChange: (transport) => {
+          this.runInZone(() => {
+            if (transport !== this._transportState()) {
+              logger.debug('Transport change via callback', { state: transport });
+              this._transportState.set(transport);
+            }
+          });
+        },
+      });
+
+      // Connect using proper ChannelConfig format. Default `origin` to
+      // `window.location.origin` so wallets always have a URL to display in
+      // the approval prompt — without this, dApps that forget to pass an
+      // origin show up as anonymous, hurting trust signals.
+      const resolvedOrigin =
+        config.appOrigin ??
+        (typeof window !== 'undefined' && window.location ? window.location.origin : undefined);
+
+      const invite = await this.client.connect({
+        type: config.type,
+        app: {
+          id: config.appId,
+          name: config.appName,
+          icon: config.appIcon,
+          origin: resolvedOrigin,
+        },
+        context: {
+          ledgerId: config.ledgerId,
+          networkId: config.networkId,
+        },
+        permissions: config.permissions,
+        relays: config.relays,
+      });
+
+      // Set up state synchronization
+      this.setupStateSync();
+
+      this.runInZone(() => {
+        this._currentInvite.set(invite);
+        this._state.set('pending');
+      });
+
+      // Store invite for reconnection
+      this.storeInvite(invite);
+
+      logger.info('Channel connection initiated', {
+        channelId: invite.id.slice(0, 8),
+        type: invite.type,
+      });
+
+      return invite;
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      logger.error('Connection failed', { error: message });
+
+      // Reset connecting flag on error
+      this.connectingNewSession = false;
+
+      this.runInZone(() => {
+        this._state.set('error');
+        this._error.set(message);
+      });
+
+      throw error;
+    }
+  }
+
+  /**
+   * Generate a wallet invite URL for the current channel.
+   *
+   * @param invite - The channel invite (defaults to current)
+   * @param walletUrl - Base URL of the wallet
+   * @returns Full URL with invite parameter
+   */
+  getWalletInviteUrl(invite?: ChannelInvite, walletUrl = DEFAULT_WALLET_URL): string {
+    const inv = invite ?? this._currentInvite();
+    if (!inv) {
+      throw new Error('No active invite');
+    }
+
+    const encoded = encodeChannelInvite(inv);
+    return `${walletUrl}?hsuite_invite=${encodeURIComponent(encoded)}`;
+  }
+
+  /**
+   * Send an RPC request to the wallet.
+   *
+   * @param method - RPC method name
+   * @param params - Method parameters
+   * @param timeoutMs - Request timeout (default: 60s)
+   * @returns The RPC response
+   */
+  async request<T = unknown>(
+    method: string,
+    params: Record<string, unknown>,
+    timeoutMs = 60000,
+  ): Promise<T> {
+    if (!this.client) {
+      throw new Error('Not connected - no active channel client. Please reconnect to the wallet.');
+    }
+
+    const state = this._state();
+    if (state !== 'active' && state !== 'approved') {
+      throw new Error(
+        `Not connected - channel state is '${state}'. Please reconnect to the wallet.`,
+      );
+    }
+
+    logger.debug('Sending RPC request', { method, state });
+
+    return this.client.request<T>(method, params, timeoutMs);
+  }
+
+  /**
+   * Sign a transaction via the wallet.
+   *
+   * @param options
+   * @param accountAddress - Signer account address
+   * @param options.accountAddress
+   * @param options.payload
+   * @param options.ledgerId
+   * @param options.networkId
+   * @param payload - Transaction payload (base64 or hex)
+   * @param ledgerId - Optional ledger override
+   * @param networkId - Optional network override
+   * @returns Sign result with signature
+   */
+  async signTransaction(options: {
+    accountAddress: string;
+    payload: string;
+    ledgerId?: string;
+    networkId?: string;
+  }): Promise<{ signature: string; signedPayload?: string; metadata?: Record<string, unknown> }> {
+    const response = await this.request<{
+      signature?: string;
+      signedPayload?: string;
+      signedTransaction?: string;
+      metadata?: Record<string, unknown>;
+    }>('ledger/sign', {
+      accountAddress: options.accountAddress,
+      payload: options.payload,
+      ledgerId: options.ledgerId,
+      networkId: options.networkId,
+    });
+
+    return {
+      signature: response.signature ?? '',
+      signedPayload: response.signedPayload ?? response.signedTransaction,
+      metadata: response.metadata,
+    };
+  }
+
+  /**
+   * Sign and submit a transaction in one call (single prompt).
+   *
+   * @param options
+   * @param accountAddress - Signer account address
+   * @param options.accountAddress
+   * @param options.payload
+   * @param options.ledgerId
+   * @param options.networkId
+   * @param options.isBatch
+   * @param options.batchKey
+   * @param options.innerTransactions
+   * @param payload - Transaction payload
+   * @param ledgerId - Optional ledger override
+   * @param networkId - Optional network override
+   * @returns Submit result with transaction ID
+   */
+  async signAndSubmitTransaction(options: {
+    accountAddress: string;
+    payload: string;
+    ledgerId?: string;
+    networkId?: string;
+    // Batch transaction fields
+    isBatch?: boolean;
+    batchKey?: string;
+    innerTransactions?: Array<{ payload: string; description?: string }>;
+  }): Promise<{
+    transactionId: string;
+    transactionHash?: string;
+    metadata?: Record<string, unknown>;
+  }> {
+    const response = await this.request<{
+      transactionId?: string;
+      transactionHash?: string;
+      metadata?: Record<string, unknown>;
+    }>('ledger/signAndSubmit', {
+      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,
+      }),
+    });
+
+    return {
+      transactionId: response.transactionId ?? '',
+      transactionHash: response.transactionHash,
+      metadata: response.metadata,
+    };
+  }
+
+  /**
+   * Disconnect from the wallet.
+   */
+  async disconnect(): Promise<void> {
+    // Stop state polling first
+    this.stopStateSync();
+
+    if (this.client) {
+      try {
+        await this.client.disconnect();
+      } catch (error) {
+        logger.warn('Disconnect error', { error });
+      }
+      this.client = null;
+    }
+
+    this.clearStoredChannel();
+
+    this.runInZone(() => {
+      this._state.set('disconnected');
+      this._transportState.set('nostr-only');
+      this._accounts.set([]);
+      this._currentInvite.set(null);
+      this._error.set(null);
+    });
+
+    logger.info('Disconnected from channel');
+  }
+
+  /**
+   * Attempt to restore a previous session.
+   *
+   * Note: This method is called by HsuiteNativeProvider as the single point
+   * of session lifecycle control. Do not call from multiple places.
+   *
+   * @returns True if restoration was successful
+   */
+  async attemptRestore(): Promise<boolean> {
+    // Skip restore if a new connection is being initiated
+    if (this.connectingNewSession) {
+      logger.debug('Skipping restore - new connection in progress');
+      return false;
+    }
+
+    const stored = this.getStoredChannel();
+    if (!stored) {
+      return false;
+    }
+
+    // §21.1 Option A: legacy persisted channels (pre-localContext-persistence)
+    // cannot be safely restored — reconnecting re-derives the Ed25519 signing
+    // keypair with empty context, producing a different pubKey than the one
+    // the peer TOFU-bound at initial connect, and the next signed message
+    // floods HWA-04 impersonation errors. Rather than silently fall through
+    // to that broken path, clear the stored channel and force a fresh scan.
+    // Safe to do unconditionally at this point in the project's lifecycle:
+    // no dApp sessions are live in production yet.
+    if (stored.localContext === undefined) {
+      logger.warn(
+        'Clearing legacy persisted channel without localContext — user must re-approve the dApp connection (§21.1)',
+        { channelId: stored.id.slice(0, 8) },
+      );
+      this.clearStoredChannel();
+      return false;
+    }
+
+    logger.info('Attempting session restore', {
+      channelId: stored.id.slice(0, 8),
+    });
+
+    this.runInZone(() => {
+      this._state.set('connecting');
+    });
+
+    try {
+      // Create client with callbacks for immediate state updates
+      this.client = new ChannelClient({
+        onStateChange: (state) => {
+          this.runInZone(() => {
+            const previousState = this._state();
+            if (state !== previousState) {
+              logger.debug('State change via callback (reconnect)', {
+                from: previousState,
+                to: state,
+              });
+              this._state.set(state);
+              if (state === 'error') {
+                const errorMsg =
+                  this.client?.state === 'error' ? 'Connection rejected or failed' : null;
+                this._error.set(errorMsg);
+              }
+              if (state === 'active' || state === 'error' || state === 'disconnected') {
+                this.connectingNewSession = false;
+              }
+              if (state === 'active' && previousState !== 'active') {
+                this.persistCurrentState();
+              }
+            }
+          });
+        },
+        onAccountsChange: (accounts) => {
+          this.runInZone(() => {
+            logger.debug('Accounts change via callback (reconnect)', { count: accounts.length });
+            this._accounts.set(accounts);
+            if (this._state() === 'active') {
+              this.persistCurrentState();
+            }
+          });
+        },
+        onTransportChange: (transport) => {
+          this.runInZone(() => {
+            if (transport !== this._transportState()) {
+              logger.debug('Transport change via callback (reconnect)', { state: transport });
+              this._transportState.set(transport);
+            }
+          });
+        },
+      });
+      // Pass the known remote peer fingerprint for P2P restoration
+      const remotePeer = stored.knownPeers?.[0];
+      await this.client.reconnect(stored, remotePeer);
+
+      this.setupStateSync();
+
+      // Restore invite and accounts from persisted/client data
+      const restoredInvite = this.client.currentInvite;
+      const restoredAccounts = this.client.accounts;
+      this.runInZone(() => {
+        if (restoredInvite) {
+          this._currentInvite.set(restoredInvite);
+        }
+        // Immediately sync accounts from the client
+        if (restoredAccounts.length > 0) {
+          this._accounts.set(restoredAccounts);
+        }
+        this._state.set('active');
+      });
+
+      logger.info('Session restored successfully', {
+        channelId: stored.id.slice(0, 8),
+        accounts: restoredAccounts.length,
+      });
+      return true;
+    } catch (error) {
+      logger.warn('Session restore failed', {
+        error: error instanceof Error ? error.message : String(error),
+      });
+
+      // Clean up the partially initialized client
+      this.client = null;
+
+      this.runInZone(() => {
+        this._state.set('disconnected');
+      });
+
+      this.clearStoredChannel();
+      return false;
+    }
+  }
+
+  // ============================================================================
+  // Private Methods
+  // ============================================================================
+
+  /**
+   * Run a function inside NgZone for proper change detection.
+   * @param fn
+   */
+  private runInZone(fn: () => void): void {
+    if (this.zone) {
+      this.zone.run(fn);
+    } else {
+      fn();
+    }
+  }
+
+  /** Current polling timeout ID for cleanup */
+  private pollingTimeoutId?: ReturnType<typeof setTimeout>;
+
+  /**
+   * Set up state synchronization from the underlying client.
+   * Polling continues as long as the client exists - it doesn't stop on disconnect/error
+   * to properly track state changes during reconnection.
+   */
+  private setupStateSync(): void {
+    if (!this.client) return;
+
+    // Clear any existing polling
+    this.stopStateSync();
+
+    // Poll for state changes (ChannelClient uses getters, not signals)
+    const checkState = () => {
+      if (!this.client) {
+        this.pollingTimeoutId = undefined;
+        return;
+      }
+
+      // Use getters directly (not function calls)
+      const clientState = this.client.state;
+      const clientAccounts = this.client.accounts;
+      const clientTransport = this.client.transportState;
+
+      this.runInZone(() => {
+        const previousState = this._state();
+        if (clientState !== previousState) {
+          this._state.set(clientState);
+          // Reset the connecting flag when connection is complete (active) or failed (error, disconnected)
+          if (
+            clientState === 'active' ||
+            clientState === 'error' ||
+            clientState === 'disconnected'
+          ) {
+            this.connectingNewSession = false;
+          }
+          // Re-store session when it becomes active (after approval with accounts)
+          if (clientState === 'active' && previousState !== 'active') {
+            this.persistCurrentState();
+          }
+        }
+        // Deep compare accounts array
+        const currentAccounts = this._accounts();
+        if (
+          clientAccounts.length !== currentAccounts.length ||
+          clientAccounts.some((acc, i) => acc.address !== currentAccounts[i]?.address)
+        ) {
+          this._accounts.set(clientAccounts);
+          // Re-persist when accounts change
+          if (clientState === 'active') {
+            this.persistCurrentState();
+          }
+        }
+        if (clientTransport !== this._transportState()) {
+          this._transportState.set(clientTransport);
+          logger.debug('Transport state updated', { state: clientTransport });
+        }
+      });
+
+      // Continue polling as long as client exists
+      // Use faster polling for active states, slower for idle/disconnected
+      if (this.client) {
+        const pollInterval =
+          clientState === 'active' ||
+          clientState === 'pending' ||
+          clientState === 'connecting' ||
+          clientState === 'approved'
+            ? 100 // Fast polling during active states
+            : 500; // Slower polling during idle/disconnected (save CPU)
+        this.pollingTimeoutId = setTimeout(checkState, pollInterval);
+      } else {
+        this.pollingTimeoutId = undefined;
+      }
+    };
+
+    this.pollingTimeoutId = setTimeout(checkState, 100);
+  }
+
+  /**
+   * Stop state synchronization polling.
+   */
+  private stopStateSync(): void {
+    if (this.pollingTimeoutId) {
+      clearTimeout(this.pollingTimeoutId);
+      this.pollingTimeoutId = undefined;
+    }
+  }
+
+  // ============================================================================
+  // Storage
+  // ============================================================================
+
+  private static readonly STORAGE_KEY = 'hsuite_channel_persisted';
+
+  /**
+   * Persist current state for reconnection after approval.
+   */
+  private persistCurrentState(): void {
+    if (!this.client) return;
+    try {
+      const persisted = this.client.exportState();
+      if (persisted) {
+        localStorage.setItem(ChannelClientService.STORAGE_KEY, JSON.stringify(persisted));
+        logger.debug('Channel state persisted', {
+          channelId: persisted.id.slice(0, 8),
+          accounts: persisted.accounts?.length ?? 0,
+        });
+      }
+    } catch (error) {
+      logger.warn('Failed to persist channel state', { error });
+    }
+  }
+
+  /**
+   * Store channel state for reconnection.
+   * Uses client's exportState() to get proper PersistedChannel format.
+   * @param invite
+   */
+  private storeInvite(invite: ChannelInvite): void {
+    try {
+      // Use the client's exportState if available, otherwise create minimal persisted data
+      const persisted = this.client?.exportState();
+      if (persisted) {
+        localStorage.setItem(ChannelClientService.STORAGE_KEY, JSON.stringify(persisted));
+      } else {
+        // Fallback: create minimal persisted channel.
+        // C-1 / SOC2 CC6.6 — `createdAt` is required on PersistedChannel
+        // so the absolute-lifetime reaper can survive a reconnect. In
+        // this fallback path we don't know the original creation time
+        // (the client didn't expose its exportState), so seed it to
+        // "now" — the worst case is the reaper waits a full lifetime
+        // from this point, which is no weaker than the previous
+        // behaviour where it had no anchor at all.
+        const now = Date.now();
+        const minimal: PersistedChannel = {
+          version: 1,
+          id: invite.id,
+          type: invite.type,
+          invitation: encodeChannelInvite(invite),
+          fingerprint: 'unknown',
+          accounts: this._accounts(),
+          knownPeers: [],
+          createdAt: now,
+          lastActivity: now,
+          isHost: false,
+        };
+        localStorage.setItem(ChannelClientService.STORAGE_KEY, JSON.stringify(minimal));
+      }
+    } catch {
+      logger.warn('Failed to store channel');
+    }
+  }
+
+  /**
+   * Retrieve stored channel for reconnection.
+   */
+  private getStoredChannel(): PersistedChannel | null {
+    try {
+      const stored = localStorage.getItem(ChannelClientService.STORAGE_KEY);
+      if (stored) {
+        return JSON.parse(stored) as PersistedChannel;
+      }
+    } catch {
+      logger.warn('Failed to retrieve stored channel');
+    }
+    return null;
+  }
+
+  /**
+   * Clear stored channel data.
+   */
+  private clearStoredChannel(): void {
+    try {
+      localStorage.removeItem(ChannelClientService.STORAGE_KEY);
+    } catch {
+      // Ignore
+    }
+  }
+}