appium-ios-remotexpc 0.21.1 → 0.22.0

package/src/lib/apple-tv/tunnel/tunnel-service.ts

@@ -0,0 +1,543 @@
+import { util } from '@appium/support';
+import { lookup } from 'node:dns/promises';
+import * as tls from 'node:tls';
+
+import type { AppleTVDevice } from '../../bonjour/bonjour-discovery.js';
+import { BonjourDiscovery } from '../../bonjour/bonjour-discovery.js';
+import { getLogger } from '../../logger.js';
+import { DEFAULT_PAIRING_CONFIG } from '../constants.js';
+import {
+  decryptChaCha20Poly1305,
+  encryptChaCha20Poly1305,
+} from '../encryption/index.js';
+import { PairingError } from '../errors.js';
+import { NetworkClient } from '../network/index.js';
+import type { NetworkClientInterface } from '../network/types.js';
+import { PairVerificationProtocol } from '../pairing-protocol/index.js';
+import type { VerificationKeys } from '../pairing-protocol/pair-verification-protocol.js';
+import { PairingStorage } from '../storage/pairing-storage.js';
+import type { PairRecord } from '../storage/types.js';
+import type { TcpListenerInfo, TlsPskConnectionOptions } from './types.js';
+
+const appleTVLog = getLogger('AppleTVTunnelService');
+
+export class TunnelService {
+  private static readonly log = getLogger('TunnelService');
+  private encryptedSequenceNumber = 0;
+
+  constructor(
+    private readonly networkClient: NetworkClientInterface,
+    private readonly keys: VerificationKeys,
+    private sequenceNumber: number,
+  ) {}
+
+  async createTcpListener(): Promise<TcpListenerInfo> {
+    TunnelService.log.debug('Creating TCP listener (Encrypted Request)');
+
+    const request = {
+      request: {
+        _0: {
+          createListener: {
+            key: this.keys.encryptionKey.toString('base64'),
+            peerConnectionsInfo: [
+              {
+                owningPID: process.pid,
+                owningProcessName: 'CoreDeviceService',
+              },
+            ],
+            transportProtocolType: 'tcp',
+          },
+        },
+      },
+    };
+
+    const nonce = Buffer.alloc(12);
+    nonce.writeBigUInt64LE(BigInt(this.encryptedSequenceNumber), 0);
+
+    const requestJson = JSON.stringify(request);
+
+    const encrypted = encryptChaCha20Poly1305({
+      plaintext: Buffer.from(requestJson, 'utf8'),
+      key: this.keys.clientEncryptionKey,
+      nonce,
+    });
+
+    const encryptedPayload = {
+      message: {
+        streamEncrypted: {
+          _0: encrypted.toString('base64'),
+        },
+      },
+      originatedBy: 'host',
+      sequenceNumber: this.sequenceNumber++,
+    };
+
+    await this.networkClient.sendPacket(encryptedPayload);
+    this.encryptedSequenceNumber++;
+
+    const response = await this.networkClient.receiveResponse();
+
+    const encryptedData = response.message?.streamEncrypted?._0;
+
+    if (!encryptedData) {
+      throw new PairingError(
+        'Failed to receive encrypted response from device',
+        'ENCRYPTED_RESPONSE_MISSING',
+        { response },
+      );
+    }
+
+    const responseNonce = Buffer.alloc(12);
+    responseNonce.writeBigUInt64LE(BigInt(this.encryptedSequenceNumber - 1), 0);
+
+    const decrypted = decryptChaCha20Poly1305({
+      ciphertext: Buffer.from(encryptedData, 'base64'),
+      key: this.keys.serverEncryptionKey,
+      nonce: responseNonce,
+    });
+
+    const responseJson = JSON.parse(decrypted.toString('utf8'));
+    const createListenerResponse = responseJson?.response?._1?.createListener;
+
+    if (!createListenerResponse?.port) {
+      TunnelService.log.error('Invalid createListener response:', responseJson);
+      throw new PairingError(
+        'TCP listener creation failed: missing port in response',
+        'LISTENER_PORT_MISSING',
+        { response: responseJson },
+      );
+    }
+
+    TunnelService.log.debug(
+      `TCP Listener created on port: ${createListenerResponse.port}`,
+    );
+
+    return createListenerResponse;
+  }
+
+  async createTlsPskConnection(
+    hostname: string,
+    port: number,
+  ): Promise<tls.TLSSocket> {
+    TunnelService.log.debug(
+      `Creating TLS-PSK connection to ${hostname}:${port}`,
+    );
+
+    return new Promise((resolve, reject) => {
+      const options: TlsPskConnectionOptions = {
+        host: hostname,
+        port,
+        pskCallback: (hint: string | null) => {
+          TunnelService.log.debug(`PSK callback invoked with hint: ${hint}`);
+          return {
+            psk: this.keys.encryptionKey,
+            identity: '',
+          };
+        },
+        ciphers:
+          'PSK-AES256-CBC-SHA:PSK-AES128-CBC-SHA:PSK-3DES-EDE-CBC-SHA:PSK-RC4-SHA:PSK',
+        secureProtocol: 'TLSv1_2_method',
+        // SECURITY NOTE: Disabling certificate validation is intentional and safe in this context.
+        // This connection uses TLS-PSK (Pre-Shared Key) authentication, where the pre-shared key
+        // itself provides mutual authentication between client and server. Traditional X.509
+        // certificate validation is not used in PSK-based TLS connections. The encryption key
+        // was securely established during the pairing process (which involves PIN verification),
+        // and this key authenticates both parties. This is the standard approach for Apple TV's
+        // RemoteXPC protocol and should NOT be changed to use certificate validation.
+        rejectUnauthorized: false,
+        checkServerIdentity: () => undefined,
+      };
+
+      const socket = tls.connect(options, () => {
+        TunnelService.log.debug('TLS-PSK connection established');
+        resolve(socket);
+      });
+
+      socket.on('error', (error: Error & { code?: string }) => {
+        TunnelService.log.error('TLS-PSK connection error:', error);
+
+        if (
+          error.message?.includes('no shared cipher') ||
+          error.code === 'ECONNRESET'
+        ) {
+          TunnelService.log.error(
+            'PSK ciphers may not be available in your Node.js build',
+          );
+          TunnelService.log.error('You may need to:');
+          TunnelService.log.error(
+            '1. Use Node.js compiled with PSK-enabled OpenSSL',
+          );
+          TunnelService.log.error(
+            '2. Use a Python subprocess for the TLS-PSK connection',
+          );
+          TunnelService.log.error('3. Use a native module like node-openssl');
+        }
+
+        reject(error);
+      });
+
+      socket.on('secureConnect', () => {
+        TunnelService.log.debug('Secure connection event fired');
+      });
+
+      socket.on('tlsClientError', (error) => {
+        TunnelService.log.error('TLS client error:', error);
+      });
+    });
+  }
+
+  getSequenceNumber(): number {
+    return this.sequenceNumber;
+  }
+}
+
+/**
+ * High-level service for establishing Apple TV tunnels.
+ * Orchestrates device discovery, pairing verification, and tunnel creation.
+ */
+export class AppleTVTunnelService {
+  private readonly networkClient: NetworkClient;
+  private readonly storage: PairingStorage;
+  private sequenceNumber = 0;
+
+  constructor() {
+    this.networkClient = new NetworkClient(DEFAULT_PAIRING_CONFIG);
+    this.storage = new PairingStorage(DEFAULT_PAIRING_CONFIG);
+  }
+
+  disconnect(): void {
+    this.networkClient.disconnect();
+  }
+
+  async startTunnel(
+    deviceId?: string,
+    specificDeviceIdentifier?: string,
+  ): Promise<{ socket: tls.TLSSocket; device: AppleTVDevice }> {
+    const devices = await this.discoverDevices();
+    this.logDiscoveredDevices(devices);
+
+    const devicesToProcess = this.selectDevicesToProcess(
+      devices,
+      specificDeviceIdentifier,
+    );
+    const identifiersToTry = await this.validateAndGetPairRecords(deviceId);
+
+    const failedAttempts: { identifier: string; error: string }[] = [];
+
+    for (const device of devicesToProcess) {
+      for (const identifier of identifiersToTry) {
+        appleTVLog.debug(
+          `\n--- Attempting connection with pair record: ${identifier} ---`,
+        );
+        appleTVLog.debug(`Device: ${device.ip}:${device.port}`);
+
+        const pairRecord = await this.storage.load(identifier);
+        if (!pairRecord) {
+          appleTVLog.debug(`Failed to load pair record for ${identifier}`);
+          failedAttempts.push({
+            identifier,
+            error: 'Failed to load pair record',
+          });
+          continue;
+        }
+
+        const result = await this.attemptDeviceConnection(
+          device,
+          identifier,
+          pairRecord,
+          failedAttempts,
+        );
+
+        if (result) {
+          return result;
+        }
+      }
+    }
+
+    this.logFailureSummary(failedAttempts);
+
+    throw new Error(
+      'Failed to establish tunnel with any pair record. All authentication attempts failed.',
+    );
+  }
+
+  /**
+   * Logs information about discovered devices
+   */
+  private logDiscoveredDevices(devices: AppleTVDevice[]): void {
+    appleTVLog.debug('Step 1: Device Discovery success');
+    appleTVLog.debug(
+      `Found ${util.pluralize('device', devices.length, true)} via Bonjour`,
+    );
+
+    if (devices.length > 0) {
+      appleTVLog.info('\nDiscovered Apple TV devices:');
+      devices.forEach((device, index) => {
+        appleTVLog.info(`  ${index + 1}. Identifier: ${device.identifier}`);
+        appleTVLog.info(`     Name: ${device.name}`);
+        appleTVLog.info(`     IP: ${device.ip}:${device.port}`);
+        appleTVLog.info(`     Model: ${device.model}`);
+        appleTVLog.info(`     Version: ${device.version}`);
+      });
+    }
+  }
+
+  /**
+   * Selects devices to process based on the specific device identifier
+   */
+  private selectDevicesToProcess(
+    devices: AppleTVDevice[],
+    specificDeviceIdentifier?: string,
+  ): AppleTVDevice[] {
+    if (!specificDeviceIdentifier) {
+      return devices;
+    }
+
+    const filteredDevices = devices.filter(
+      (device) => device.identifier === specificDeviceIdentifier,
+    );
+
+    if (filteredDevices.length === 0) {
+      appleTVLog.error(
+        `\nDevice with identifier ${specificDeviceIdentifier} not found in discovered devices.`,
+      );
+      appleTVLog.error('Available devices:');
+      devices.forEach((device) => {
+        appleTVLog.error(`  - ${device.identifier} (${device.name})`);
+      });
+      throw new Error(
+        `Device with identifier ${specificDeviceIdentifier} not found. Please check available devices above.`,
+      );
+    }
+
+    appleTVLog.info(
+      `\nFiltered to specific device: ${specificDeviceIdentifier}`,
+    );
+
+    return filteredDevices;
+  }
+
+  /**
+   * Validates pair records and returns the list of identifiers to try
+   */
+  private async validateAndGetPairRecords(
+    deviceId?: string,
+  ): Promise<string[]> {
+    const availableDeviceIds = await this.storage.getAvailableDeviceIds();
+
+    if (availableDeviceIds.length === 0) {
+      throw new Error('No pair records found');
+    }
+
+    if (deviceId && !availableDeviceIds.includes(deviceId)) {
+      throw new Error(`No pair record found for specified device ${deviceId}`);
+    }
+
+    return deviceId ? [deviceId] : availableDeviceIds;
+  }
+
+  /**
+   * Attempts to establish a connection with a device using a specific pair record
+   */
+  private async attemptDeviceConnection(
+    device: AppleTVDevice,
+    identifier: string,
+    pairRecord: PairRecord,
+    failedAttempts: { identifier: string; error: string }[],
+  ): Promise<{ socket: tls.TLSSocket; device: AppleTVDevice } | null> {
+    try {
+      this.sequenceNumber = 0;
+      await this.networkClient.connect(device.ip!, device.port);
+
+      try {
+        await this.performHandshake();
+
+        const keys = await this.performPairVerification(pairRecord, identifier);
+        appleTVLog.info(
+          `✅ Successfully verified with pair record: ${identifier}`,
+        );
+
+        const listenerInfo = await this.createTcpListener(keys);
+        this.networkClient.disconnect();
+
+        const tlsSocket = await this.createTlsPskConnection(
+          device.ip!,
+          listenerInfo.port,
+          keys,
+        );
+
+        appleTVLog.debug('Step 6: Tunnel Establishment success');
+        appleTVLog.info(`🔑 Using pair record: ${identifier}`);
+        appleTVLog.info(
+          `📱 Connected to device: ${device.identifier} (${device.name})`,
+        );
+        appleTVLog.info(`   IP: ${device.ip}:${device.port}`);
+
+        return { socket: tlsSocket, device };
+      } catch (error: any) {
+        const errorMessage = error.message || String(error);
+        appleTVLog.debug(
+          `❌ Failed with pair record ${identifier}: ${errorMessage}`,
+        );
+        failedAttempts.push({ identifier, error: errorMessage });
+        this.networkClient.disconnect();
+        await new Promise((resolve) => setTimeout(resolve, 500));
+      }
+    } catch (connectionError: any) {
+      const errorMessage = connectionError.message || String(connectionError);
+      appleTVLog.debug(
+        `Failed to connect to ${device.ip}:${device.port}: ${errorMessage}`,
+      );
+      failedAttempts.push({
+        identifier,
+        error: `Connection failed: ${errorMessage}`,
+      });
+      this.networkClient.disconnect();
+    }
+
+    return null;
+  }
+
+  /**
+   * Logs a summary of all failed connection attempts
+   */
+  private logFailureSummary(
+    failedAttempts: { identifier: string; error: string }[],
+  ): void {
+    appleTVLog.error('\n=== Pair Record Verification Summary ===');
+    appleTVLog.error(`Total pair records tried: ${failedAttempts.length}`);
+    failedAttempts.forEach(({ identifier, error }) => {
+      appleTVLog.error(`  - ${identifier}: ${error}`);
+    });
+    appleTVLog.error('=======================================\n');
+  }
+
+  private async discoverDevices(): Promise<AppleTVDevice[]> {
+    const discovery = new BonjourDiscovery();
+
+    await discovery.startBrowsing('_remotepairing._tcp', 'local');
+    await new Promise((resolve) =>
+      setTimeout(resolve, DEFAULT_PAIRING_CONFIG.discoveryTimeout),
+    );
+
+    const services = discovery.getDiscoveredServices();
+    const devices: AppleTVDevice[] = [];
+
+    for (const service of services) {
+      try {
+        const resolved = await discovery.resolveService(
+          service.name,
+          '_remotepairing._tcp',
+          'local',
+        );
+
+        if (resolved.hostname && resolved.port) {
+          const ipResult = await lookup(
+            resolved.hostname.endsWith('.')
+              ? resolved.hostname.slice(0, -1)
+              : resolved.hostname,
+            { family: 4 },
+          );
+
+          devices.push({
+            name: resolved.name,
+            identifier: resolved.txtRecord?.identifier || resolved.name,
+            hostname: resolved.hostname,
+            ip: ipResult.address,
+            port: resolved.port,
+            model: resolved.txtRecord?.model || '',
+            version: resolved.txtRecord?.ver || '',
+            minVersion: resolved.txtRecord?.minVer || '17',
+          });
+        }
+      } catch (err) {
+        appleTVLog.debug(`Failed to resolve service ${service.name}: ${err}`);
+      }
+    }
+
+    discovery.stopBrowsing();
+
+    if (devices.length === 0) {
+      throw new Error('No devices found via Bonjour discovery');
+    }
+
+    return devices;
+  }
+
+  private async performHandshake(): Promise<void> {
+    const handshakePayload = {
+      message: {
+        plain: {
+          _0: {
+            request: {
+              _0: {
+                handshake: {
+                  _0: {
+                    hostOptions: { attemptPairVerify: true },
+                    wireProtocolVersion: 19,
+                  },
+                },
+              },
+            },
+          },
+        },
+      },
+      originatedBy: 'host',
+      sequenceNumber: this.sequenceNumber++,
+    };
+
+    await this.networkClient.sendPacket(handshakePayload);
+    await this.networkClient.receiveResponse();
+
+    appleTVLog.debug('Step 2: Initial Connection & Handshake success');
+  }
+
+  private async performPairVerification(
+    pairRecord: PairRecord,
+    deviceId: string,
+  ): Promise<VerificationKeys> {
+    appleTVLog.debug('Step 3: Pair Verification (4-step process)');
+
+    const verificationProtocol = new PairVerificationProtocol(
+      this.networkClient,
+    );
+    verificationProtocol.setSequenceNumber(this.sequenceNumber);
+    const keys = await verificationProtocol.verify(pairRecord, deviceId);
+
+    this.sequenceNumber = verificationProtocol.getSequenceNumber();
+
+    appleTVLog.debug('Step 4: Main Encryption Key Derivation success');
+
+    return keys;
+  }
+
+  private async createTcpListener(
+    keys: VerificationKeys,
+  ): Promise<{ port: number; serviceName: string; devicePublicKey: string }> {
+    appleTVLog.debug('Step 5: TCP Listener Creation (Encrypted Request)');
+
+    const tunnelService = new TunnelService(
+      this.networkClient,
+      keys,
+      this.sequenceNumber,
+    );
+    const listenerInfo = await tunnelService.createTcpListener();
+
+    this.sequenceNumber = tunnelService.getSequenceNumber();
+
+    return listenerInfo;
+  }
+
+  private async createTlsPskConnection(
+    hostname: string,
+    port: number,
+    keys: VerificationKeys,
+  ): Promise<tls.TLSSocket> {
+    const tunnelService = new TunnelService(
+      this.networkClient,
+      keys,
+      this.sequenceNumber,
+    );
+    return tunnelService.createTlsPskConnection(hostname, port);
+  }
+}

package/src/lib/apple-tv/tunnel/types.ts

@@ -0,0 +1,23 @@
+import type * as tls from 'node:tls';
+
+export interface TcpListenerInfo {
+  port: number;
+  serviceName: string;
+  devicePublicKey: string;
+}
+
+/**
+ * Extended TLS connection options that include PSK (Pre-Shared Key) callback support.
+ * This interface extends the standard Node.js TLS ConnectionOptions to add PSK authentication.
+ */
+export interface TlsPskConnectionOptions extends tls.ConnectionOptions {
+  /**
+   * Callback function invoked during TLS handshake to provide PSK credentials.
+   * @param hint - Optional hint from the server about which PSK identity to use
+   * @returns Object containing the pre-shared key and identity string
+   */
+  pskCallback?: (hint: string | null) => {
+    psk: Buffer;
+    identity: string;
+  };
+}

package/src/lib/bonjour/bonjour-discovery.ts

@@ -446,7 +446,7 @@ export class BonjourDiscovery extends EventEmitter {
       return;
     }
 
-    log.info(`Starting Bonjour discovery for ${serviceType}.${domain}`);
+    log.info('Starting Bonjour discovery');
 
     try {
       await this.initializeBrowsing(serviceType, domain);
@@ -482,9 +482,7 @@ export class BonjourDiscovery extends EventEmitter {
     serviceType: string = BONJOUR_SERVICE_TYPES.APPLE_TV_PAIRING,
     domain: string = BONJOUR_DEFAULT_DOMAIN,
   ): Promise<BonjourService> {
-    log.info(
-      `[ServiceResolver] Resolving service: ${serviceName}.${serviceType}.${domain}`,
-    );
+    log.info(`[ServiceResolver] Resolving service: ${serviceName}`);
 
     const service = await executeDnsSdCommand<BonjourService | null>(
       [DNS_SD_COMMANDS.RESOLVE, serviceName, serviceType, domain],
@@ -538,7 +536,7 @@ export class BonjourDiscovery extends EventEmitter {
         case DNS_SD_ACTIONS.ADD:
           this._discoveredServices.set(service.name, service);
           this.emit('serviceAdded', service);
-          log.info(`Discovered service: ${service.name}`);
+          log.debug(`Discovered service: ${service.name}`);
           break;
         case DNS_SD_ACTIONS.REMOVE:
           this._discoveredServices.delete(service.name);

package/src/lib/lockdown/index.ts

@@ -43,13 +43,6 @@ interface SessionInfo {
   enableSessionSSL: boolean;
 }
 
-interface StartSessionRequest {
-  Label: string;
-  Request: string;
-  HostID: string;
-  SystemBUID: string;
-}
-
 interface StartSessionResponse {
   Request?: string;
   SessionID?: PlistValue;

package/src/lib/plist/length-based-splitter.ts

@@ -93,13 +93,6 @@ export class LengthBasedSplitter extends Transform {
       // Add the new chunk to our buffer
       this.buffer = Buffer.concat([this.buffer, chunk]);
 
-      // Check if this is XML data or binary plist before doing any other processing
-      const bufferString = this.buffer.toString(
-        UTF8_ENCODING,
-        0,
-        Math.min(MAX_PREVIEW_LENGTH, this.buffer.length),
-      );
-
       // Check for binary plist format (bplist00 or Ibplist00)
       if (this.buffer.length >= BINARY_PLIST_HEADER_LENGTH) {
         const possibleBplistHeader = this.buffer.toString(
@@ -236,26 +229,11 @@ export class LengthBasedSplitter extends Transform {
           if (alternateLength > 0 && alternateLength <= this.maxFrameLength) {
             messageLength = alternateLength;
           } else {
-            // If length is still invalid, check if this might actually be XML
-            const suspiciousData = this.buffer.toString(
-              UTF8_ENCODING,
-              0,
-              Math.min(MAX_PREVIEW_LENGTH, this.buffer.length),
-            );
-
             // Invalid length - skip one byte and try again
             this.buffer = this.buffer.slice(1);
             continue;
           }
         } else {
-          // For non-4-byte length fields, just use the original approach
-          // If length is invalid, check if this might actually be XML
-          const suspiciousData = this.buffer.toString(
-            UTF8_ENCODING,
-            0,
-            Math.min(MAX_PREVIEW_LENGTH, this.buffer.length),
-          );
-
           // Invalid length - skip one byte and try again
           this.buffer = this.buffer.slice(1);
           continue;

package/src/lib/tunnel/index.ts

@@ -19,14 +19,6 @@ interface TunnelRegistryEntry {
   remoteXPC?: RemoteXpcConnection;
 }
 
-/**
- * Interface for tunnel and RemoteXPC connection result
- */
-interface TunnelResult {
-  tunnel: TunnelConnection;
-  remoteXPC: RemoteXpcConnection;
-}
-
 /**
  * A wrapper around the tunnel connection that
  * maintains a registry of active tunnels that can be reused.
@@ -256,3 +248,5 @@ export const TunnelManager = new TunnelManagerService();
 // Export packet streaming IPC functionality
 export { PacketStreamClient } from './packet-stream-client.js';
 export { PacketStreamServer } from './packet-stream-server.js';
+// Re-export TunnelConnection type from appium-ios-tuntap
+export type { TunnelConnection };

package/src/lib/tunnel/packet-stream-server.ts

@@ -6,14 +6,6 @@ import { getLogger } from '../logger.js';
 
 const log = getLogger('PacketStreamServer');
 
-/**
- * Interface for serialized packet message
- */
-interface SerializedPacketMessage {
-  length: string;
-  data: string;
-}
-
 /**
  * Server that exposes packet streaming from a tunnel over TCP
  * This allows cross-process access to tunnel packet streams

package/src/lib/tunnel/tunnel-registry-server.ts

@@ -5,7 +5,7 @@ import { getLogger } from '../logger.js';
 import type { TunnelRegistry, TunnelRegistryEntry } from '../types.js';
 
 // Constants
-const DEFAULT_TUNNEL_REGISTRY_PORT = 42314;
+export const DEFAULT_TUNNEL_REGISTRY_PORT = 42314;
 const API_BASE_PATH = '/remotexpc/tunnels';
 
 // Logger instance