appium-ios-remotexpc 0.12.0 → 0.13.0

package/build/src/lib/bonjour/bonjour-discovery.js

@@ -360,6 +360,8 @@ export class BonjourDiscovery extends EventEmitter {
         }
         finally {
             this.stopBrowsing();
+            // Small delay to ensure cleanup logs are flushed before returning
+            await delay(100);
         }
     }
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "appium-ios-remotexpc",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "main": "build/src/index.js",
   "types": "build/src/index.d.ts",
   "type": "module",
@@ -32,11 +32,13 @@
     "test:image-mounter": "mocha test/integration/mobile-image-mounter-test.ts --exit --timeout 1m",
     "test:mobile-config": "mocha test/integration/mobile-config-test.ts --exit --timeout 1m",
     "test:springboard": "mocha test/integration/springboard-service-test.ts --exit --timeout 1m",
+    "test:unit": "NODE_ENV=test mocha 'test/unit/**/*.ts' --exit --timeout 2m",
+    "tunnel-creation": "sudo tsx scripts/test-tunnel-creation.ts",
+    "pair-appletv": "sudo tsx scripts/pair-appletv.ts",
     "test:webinspector": "mocha test/integration/webinspector-test.ts --exit --timeout 1m",
     "test:misagent": "mocha test/integration/misagent-service-test.ts --exit --timeout 1m",
     "test:afc": "mocha test/integration/afc-test.ts --exit --timeout 1m",
     "test:power-assertion": "mocha test/integration/power-assertion-test.ts --exit --timeout 1m",
-    "test:unit": "mocha 'test/unit/**/*.ts' --exit --timeout 2m",
     "test:tunnel-creation": "sudo tsx scripts/test-tunnel-creation.ts",
     "test:tunnel-creation:lsof": "sudo tsx scripts/test-tunnel-creation.ts --keep-open"
   },

package/scripts/pair-appletv.ts

@@ -0,0 +1,79 @@
+#!/usr/bin/env tsx
+import { logger } from '@appium/support';
+
+import {
+  AppleTVPairingService,
+  UserInputService,
+} from '../src/lib/apple-tv/index.js';
+
+interface CLIArgs {
+  device?: string;
+  help?: boolean;
+}
+
+function parseArgs(): CLIArgs {
+  const args: CLIArgs = {};
+  const cliArgs = process.argv.slice(2);
+
+  for (let i = 0; i < cliArgs.length; i++) {
+    const arg = cliArgs[i];
+    if (arg === '--device' || arg === '-d') {
+      args.device = cliArgs[++i];
+    } else if (arg === '--help' || arg === '-h') {
+      args.help = true;
+    }
+  }
+
+  return args;
+}
+
+function printHelp(): void {
+  // eslint-disable-next-line no-console
+  console.log(`
+Apple TV Pairing Script
+
+Usage: pair-appletv [options]
+
+Options:
+  -d, --device <selector>   Specify device to pair with. Can be:
+                            - Device name (e.g., "Living Room")
+                            - Device identifier (e.g., "AA:BB:CC:DD:EE:FF")
+                            - Device index (e.g., "0", "1", "2")
+                            If not specified and multiple devices are found,
+                            you will be prompted to choose one.
+  -h, --help               Show this help message
+
+Examples:
+  pair-appletv                           # Discover and select device interactively
+  pair-appletv --device "Living Room"    # Pair with device named "Living Room"
+  pair-appletv --device 0                # Pair with first discovered device
+  pair-appletv -d AA:BB:CC:DD:EE:FF      # Pair with device by identifier
+`);
+}
+
+// CLI interface
+async function main(): Promise<void> {
+  const log = logger.getLogger('AppleTVPairing');
+  const args = parseArgs();
+
+  if (args.help) {
+    printHelp();
+    return;
+  }
+
+  const userInput = new UserInputService();
+  const pairingService = new AppleTVPairingService(userInput);
+  const result = await pairingService.discoverAndPair(args.device);
+
+  if (result.success) {
+    log.info(`Pairing successful! Record saved to: ${result.pairingFile}`);
+  } else {
+    const error = result.error ?? new Error('Pairing failed');
+    log.error(`Pairing failed: ${error.message}`);
+    throw error;
+  }
+}
+
+main().catch(() => {
+  process.exit(1);
+});

package/scripts/test-tunnel-creation.ts

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env tsx
 /**
  * Test script for creating lockdown service, starting CoreDeviceProxy, and creating tunnel
  * This script demonstrates the tunnel creation workflow for all connected devices

package/src/constants.ts

@@ -0,0 +1,4 @@
+// Global constants used across the appium-ios-remotexpc package
+
+// Strongbox container name for storing credentials and configuration
+export const STRONGBOX_CONTAINER_NAME = 'appium-ios-remotexpc';

package/src/index.ts

@@ -1,3 +1,4 @@
+import { STRONGBOX_CONTAINER_NAME } from './constants.js';
 import { createLockdownServiceByUDID } from './lib/lockdown/index.js';
 import {
   PacketStreamClient,
@@ -38,6 +39,7 @@ export type {
 } from './lib/types.js';
 export { PowerAssertionType } from './lib/types.js';
 export {
+  STRONGBOX_CONTAINER_NAME,
   createUsbmux,
   Services,
   Usbmux,

package/src/lib/apple-tv/constants.ts

@@ -3,7 +3,6 @@ export const DEFAULT_PAIRING_CONFIG = {
   timeout: 30000,
   discoveryTimeout: 5000,
   maxRetries: 3,
-  pairingDirectory: '.pairing',
 } as const;
 
 // TLV8 component type identifiers used in pairing data exchange

package/src/lib/apple-tv/discovery/device-discovery.ts

@@ -0,0 +1,34 @@
+import { logger } from '@appium/support';
+
+import {
+  type AppleTVDevice,
+  BonjourDiscovery,
+} from '../../bonjour/bonjour-discovery.js';
+import { PairingError } from '../errors.js';
+import type { PairingConfig } from '../types.js';
+
+/** Discovers Apple TV devices on the local network using Bonjour */
+export class DeviceDiscoveryService {
+  private readonly log = logger.getLogger('DeviceDiscoveryService');
+
+  constructor(private readonly config: PairingConfig) {}
+
+  async discoverDevices(): Promise<AppleTVDevice[]> {
+    try {
+      const discovery = new BonjourDiscovery();
+      this.log.info(
+        `Discovering Apple TV devices (waiting ${this.config.discoveryTimeout / 1000} seconds)...`,
+      );
+      return await discovery.discoverAppleTVDevicesWithIP(
+        this.config.discoveryTimeout,
+      );
+    } catch (error) {
+      this.log.error('Device discovery failed:', error);
+      throw new PairingError(
+        'Device discovery failed',
+        'DISCOVERY_ERROR',
+        error,
+      );
+    }
+  }
+}

package/src/lib/apple-tv/discovery/index.ts

@@ -0,0 +1 @@
+export { DeviceDiscoveryService } from './device-discovery.js';

package/src/lib/apple-tv/index.ts

@@ -17,3 +17,8 @@ export * from './deviceInfo/index.js';
 export * from './encryption/index.js';
 export * from './tlv/index.js';
 export * from './srp/index.js';
+export * from './network/index.js';
+export * from './pairing-protocol/index.js';
+export * from './storage/index.js';
+export * from './discovery/index.js';
+export * from './pairing/index.js';

package/src/lib/apple-tv/network/constants.ts

@@ -0,0 +1,9 @@
+/** Constants for network protocol */
+export const NETWORK_CONSTANTS = {
+  MAGIC: 'RPPairing',
+  MAGIC_LENGTH: 9,
+  HEADER_LENGTH: 11,
+  LENGTH_FIELD_SIZE: 2,
+  MAX_TLV_FRAGMENT_SIZE: 255,
+  PIN_INPUT_TIMEOUT_MS: 30000,
+} as const;

package/src/lib/apple-tv/network/index.ts

@@ -0,0 +1,3 @@
+export { NetworkClient } from './network-client.js';
+export { NETWORK_CONSTANTS } from './constants.js';
+export type { NetworkClientInterface } from './types.js';

package/src/lib/apple-tv/network/network-client.ts

@@ -0,0 +1,214 @@
+import { logger } from '@appium/support';
+import * as net from 'node:net';
+
+import { NetworkError } from '../errors.js';
+import type { PairingConfig } from '../types.js';
+import { NETWORK_CONSTANTS } from './constants.js';
+import type { NetworkClientInterface } from './types.js';
+
+const log = logger.getLogger('NetworkClient');
+
+/** Handles TCP socket communication with Apple TV devices */
+export class NetworkClient implements NetworkClientInterface {
+  private socket: net.Socket | null = null;
+  private connectionTimeoutId: NodeJS.Timeout | null = null;
+
+  constructor(private readonly config: PairingConfig) {}
+
+  async connect(ip: string, port: number): Promise<void> {
+    log.debug(`Connecting to ${ip}:${port}`);
+
+    return new Promise((resolve, reject) => {
+      const cancelTimeout = () => {
+        if (this.connectionTimeoutId) {
+          clearTimeout(this.connectionTimeoutId);
+          this.connectionTimeoutId = null;
+        }
+      };
+
+      this.socket = new net.Socket();
+      this.socket.setTimeout(this.config.timeout);
+
+      this.socket.once('connect', () => {
+        log.debug('Connected successfully');
+        cancelTimeout();
+        resolve();
+      });
+
+      this.socket.once('error', (error) => {
+        log.error('Connection error:', error);
+        cancelTimeout();
+        reject(new NetworkError(`Connection failed: ${error.message}`));
+      });
+
+      this.socket.once('timeout', () => {
+        log.error('Socket timeout');
+        cancelTimeout();
+        reject(new NetworkError('Socket timeout'));
+      });
+
+      this.socket.once('close', () => {
+        cancelTimeout();
+      });
+
+      this.connectionTimeoutId = setTimeout(() => {
+        log.error('Connection attempt timeout');
+        this.cleanup();
+        reject(
+          new NetworkError(`Connection timeout after ${this.config.timeout}ms`),
+        );
+      }, this.config.timeout);
+
+      this.socket.connect(port, ip);
+    });
+  }
+
+  async sendPacket(data: any): Promise<void> {
+    if (!this.socket) {
+      throw new NetworkError('Socket not connected');
+    }
+
+    const packet = this.createRPPairingPacket(data);
+    log.debug('Sending packet:', { size: packet.length });
+
+    return new Promise((resolve, reject) => {
+      if (!this.socket) {
+        reject(new NetworkError('Socket disconnected during send'));
+        return;
+      }
+
+      this.socket.write(packet, (error) => {
+        if (error) {
+          log.error('Send packet error:', error);
+          reject(new NetworkError('Failed to send packet'));
+        } else {
+          resolve();
+        }
+      });
+    });
+  }
+
+  async receiveResponse(): Promise<any> {
+    if (!this.socket) {
+      throw new NetworkError('Socket not connected');
+    }
+
+    return new Promise((resolve, reject) => {
+      let buffer = Buffer.alloc(0);
+      let expectedLength: number | null = null;
+      let headerRead = false;
+      let timeoutId: NodeJS.Timeout | null = null;
+
+      const cleanup = () => {
+        if (timeoutId) {
+          clearTimeout(timeoutId);
+          timeoutId = null;
+        }
+        if (this.socket) {
+          this.socket.removeListener('data', onData);
+          this.socket.removeListener('error', onError);
+        }
+      };
+
+      const onData = (chunk: Buffer) => {
+        try {
+          buffer = Buffer.concat([buffer, chunk]);
+
+          if (!headerRead && buffer.length >= NETWORK_CONSTANTS.HEADER_LENGTH) {
+            const magic = buffer
+              .slice(0, NETWORK_CONSTANTS.MAGIC_LENGTH)
+              .toString('ascii');
+            if (magic !== NETWORK_CONSTANTS.MAGIC) {
+              throw new NetworkError(
+                `Invalid protocol magic: expected '${NETWORK_CONSTANTS.MAGIC}', got '${magic}'`,
+              );
+            }
+            expectedLength = buffer.readUInt16BE(
+              NETWORK_CONSTANTS.MAGIC_LENGTH,
+            );
+            headerRead = true;
+            log.debug(
+              `Response header parsed: expecting ${expectedLength} bytes`,
+            );
+          }
+
+          if (
+            headerRead &&
+            expectedLength !== null &&
+            buffer.length >= NETWORK_CONSTANTS.HEADER_LENGTH + expectedLength
+          ) {
+            const bodyBytes = buffer.slice(
+              NETWORK_CONSTANTS.HEADER_LENGTH,
+              NETWORK_CONSTANTS.HEADER_LENGTH + expectedLength,
+            );
+            const response = JSON.parse(bodyBytes.toString('utf8'));
+            log.debug('Response received and parsed successfully');
+            cleanup();
+            resolve(response);
+          }
+        } catch (error) {
+          log.error('Parse response error:', error);
+          cleanup();
+          reject(
+            new NetworkError(
+              `Failed to parse response: ${(error as Error).message}`,
+            ),
+          );
+        }
+      };
+
+      const onError = (error: Error) => {
+        log.error('Socket error during receive:', error);
+        cleanup();
+        reject(new NetworkError(`Socket error: ${error.message}`));
+      };
+
+      const onClose = () => {
+        if (timeoutId) {
+          clearTimeout(timeoutId);
+        }
+      };
+
+      if (this.socket) {
+        this.socket.once('data', onData);
+        this.socket.once('error', onError);
+        this.socket.once('close', onClose);
+
+        timeoutId = setTimeout(() => {
+          log.error(`Response timeout after ${this.config.timeout}ms`);
+          cleanup();
+          reject(
+            new NetworkError(`Response timeout after ${this.config.timeout}ms`),
+          );
+        }, this.config.timeout);
+      } else {
+        reject(new NetworkError('Socket not available'));
+      }
+    });
+  }
+
+  disconnect(): void {
+    this.cleanup();
+  }
+
+  private createRPPairingPacket(jsonData: any): Buffer {
+    const jsonString = JSON.stringify(jsonData);
+    const bodyBytes = Buffer.from(jsonString, 'utf8');
+    const magic = Buffer.from(NETWORK_CONSTANTS.MAGIC, 'ascii');
+    const length = Buffer.alloc(NETWORK_CONSTANTS.LENGTH_FIELD_SIZE);
+    length.writeUInt16BE(bodyBytes.length, 0);
+    return Buffer.concat([magic, length, bodyBytes]);
+  }
+
+  private cleanup(): void {
+    if (this.connectionTimeoutId) {
+      clearTimeout(this.connectionTimeoutId);
+      this.connectionTimeoutId = null;
+    }
+    if (this.socket) {
+      this.socket.removeAllListeners();
+      this.socket.destroy();
+      this.socket = null;
+    }
+  }
+}

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

@@ -0,0 +1,7 @@
+/** Interface for network communication with Apple TV devices */
+export interface NetworkClientInterface {
+  connect(ip: string, port: number): Promise<void>;
+  sendPacket(data: any): Promise<void>;
+  receiveResponse(): Promise<any>;
+  disconnect(): void;
+}

package/src/lib/apple-tv/pairing/index.ts

@@ -0,0 +1,2 @@
+export { UserInputService } from './user-input-service.js';
+export { AppleTVPairingService } from './pairing-service.js';

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

@@ -0,0 +1,175 @@
+import type { AppleTVDevice } from '../../bonjour/bonjour-discovery.js';
+import { getLogger } from '../../logger.js';
+import { DEFAULT_PAIRING_CONFIG } from '../constants.js';
+import { DeviceDiscoveryService } from '../discovery/index.js';
+import { PairingError } from '../errors.js';
+import { NetworkClient } from '../network/index.js';
+import { PairingProtocol } from '../pairing-protocol/index.js';
+import type { UserInputInterface } from '../pairing-protocol/types.js';
+import type { PairingConfig, PairingResult } from '../types.js';
+
+const log = getLogger('AppleTVPairingService');
+
+/** Main service orchestrating Apple TV device discovery and pairing */
+export class AppleTVPairingService {
+  private readonly networkClient: NetworkClient;
+  private readonly discoveryService: DeviceDiscoveryService;
+  private readonly userInput: UserInputInterface;
+  private readonly pairingProtocol: PairingProtocol;
+
+  constructor(
+    userInput: UserInputInterface,
+    config: PairingConfig = DEFAULT_PAIRING_CONFIG,
+  ) {
+    this.networkClient = new NetworkClient(config);
+    this.discoveryService = new DeviceDiscoveryService(config);
+    this.userInput = userInput;
+    this.pairingProtocol = new PairingProtocol(
+      this.networkClient,
+      this.userInput,
+    );
+  }
+
+  async discoverAndPair(deviceSelector?: string): Promise<PairingResult> {
+    try {
+      const devices = await this.discoveryService.discoverDevices();
+
+      if (devices.length === 0) {
+        const errorMessage =
+          'No Apple TV pairing devices found. Please ensure your Apple TV is on the same network and in pairing mode.';
+        log.error(errorMessage);
+        throw new PairingError(errorMessage, 'NO_DEVICES');
+      }
+
+      const device = await this.selectDevice(devices, deviceSelector);
+      const pairingFile = await this.pairWithDevice(device);
+
+      return {
+        success: true,
+        deviceId: device.identifier,
+        pairingFile,
+      };
+    } catch (error) {
+      log.error('Pairing failed:', error);
+      return {
+        success: false,
+        deviceId: 'unknown',
+        error: error instanceof Error ? error : new Error(String(error)),
+      };
+    }
+  }
+
+  async pairWithDevice(device: AppleTVDevice): Promise<string> {
+    try {
+      // Use IP if available, otherwise fall back to hostname
+      const connectionTarget = device.ip ?? device.hostname;
+
+      if (!connectionTarget) {
+        throw new PairingError(
+          'Neither IP address nor hostname available for device',
+          'NO_CONNECTION_TARGET',
+        );
+      }
+
+      log.info(
+        `Connecting to device ${device.name} at ${connectionTarget}:${device.port}`,
+      );
+      await this.networkClient.connect(connectionTarget, device.port);
+      return await this.pairingProtocol.executePairingFlow(device);
+    } catch (error) {
+      log.error(`Pairing with device ${device.name} failed:`, error);
+      throw error;
+    } finally {
+      this.networkClient.disconnect();
+    }
+  }
+
+  private async selectDevice(
+    devices: AppleTVDevice[],
+    deviceSelector?: string,
+  ): Promise<AppleTVDevice> {
+    // If no selector provided, always prompt user to choose (even for single device)
+    if (!deviceSelector) {
+      log.info(`Found ${devices.length} device(s):`);
+      devices.forEach((device, index) => {
+        log.info(
+          `  [${index}] ${device.name} (${device.identifier}) - ${device.model} v${device.version}`,
+        );
+      });
+
+      const prompt =
+        devices.length === 1
+          ? 'Press Enter to select device [0], or enter index: '
+          : `Select device by index (0-${devices.length - 1}): `;
+
+      const indexStr = await this.userInput.promptForInput(prompt);
+      const trimmed = indexStr.trim();
+
+      // If user just presses Enter and there's only one device, select it
+      if (trimmed === '' && devices.length === 1) {
+        log.info(
+          `Selected device: ${devices[0].name} (${devices[0].identifier})`,
+        );
+        return devices[0];
+      }
+
+      const index = parseInt(trimmed, 10);
+
+      if (isNaN(index) || index < 0 || index >= devices.length) {
+        throw new PairingError(
+          `Invalid device index: ${trimmed}. Must be between 0 and ${devices.length - 1}`,
+          'INVALID_DEVICE_SELECTION',
+        );
+      }
+
+      log.info(
+        `Selected device: ${devices[index].name} (${devices[index].identifier})`,
+      );
+      return devices[index];
+    }
+
+    // Try to match by index first
+    const indexMatch = parseInt(deviceSelector, 10);
+    if (!isNaN(indexMatch) && indexMatch >= 0 && indexMatch < devices.length) {
+      log.info(
+        `Selected device by index ${indexMatch}: ${devices[indexMatch].name}`,
+      );
+      return devices[indexMatch];
+    }
+
+    // Try to match by name (case-insensitive)
+    const nameMatch = devices.find(
+      (device) => device.name.toLowerCase() === deviceSelector.toLowerCase(),
+    );
+    if (nameMatch) {
+      log.info(
+        `Selected device by name: ${nameMatch.name} (${nameMatch.identifier})`,
+      );
+      return nameMatch;
+    }
+
+    // Try to match by identifier (case-insensitive)
+    const identifierMatch = devices.find(
+      (device) =>
+        device.identifier.toLowerCase() === deviceSelector.toLowerCase(),
+    );
+    if (identifierMatch) {
+      log.info(
+        `Selected device by identifier: ${identifierMatch.name} (${identifierMatch.identifier})`,
+      );
+      return identifierMatch;
+    }
+
+    // No match found
+    const availableDevices = devices
+      .map(
+        (device, index) => `  [${index}] ${device.name} (${device.identifier})`,
+      )
+      .join('\n');
+
+    throw new PairingError(
+      `Device '${deviceSelector}' not found. Available devices:\n${availableDevices}`,
+      'DEVICE_NOT_FOUND',
+    );
+  }
+}

package/src/lib/apple-tv/pairing/user-input-service.ts

@@ -0,0 +1,71 @@
+import { logger } from '@appium/support';
+import { createInterface } from 'node:readline';
+
+import { PairingError } from '../errors.js';
+import { NETWORK_CONSTANTS } from '../network/constants.js';
+import type { UserInputInterface } from '../pairing-protocol/types.js';
+
+/** Handles user interaction for PIN input during pairing */
+export class UserInputService implements UserInputInterface {
+  private readonly log = logger.getLogger('UserInputService');
+
+  async promptForPIN(): Promise<string> {
+    const rl = createInterface({
+      input: process.stdin,
+      output: process.stdout,
+    });
+
+    let timeoutId: NodeJS.Timeout | null = null;
+
+    try {
+      const pin = await new Promise<string>((resolve, reject) => {
+        timeoutId = setTimeout(() => {
+          reject(new PairingError('PIN input timeout', 'INPUT_TIMEOUT'));
+        }, NETWORK_CONSTANTS.PIN_INPUT_TIMEOUT_MS);
+
+        rl.question('Enter PIN from Apple TV screen: ', (answer) => {
+          // Clear timeout since we got the PIN
+          if (timeoutId) {
+            clearTimeout(timeoutId);
+            timeoutId = null;
+          }
+          resolve(answer);
+        });
+      });
+
+      const cleanPin = pin.trim();
+      if (!/^\d+$/.test(cleanPin)) {
+        this.log.error('Invalid PIN format');
+        throw new PairingError('PIN must contain only digits', 'INVALID_PIN');
+      }
+
+      this.log.debug('PIN received successfully');
+      return cleanPin;
+    } finally {
+      // Clean up timeout if error occurred before clearing
+      if (timeoutId) {
+        clearTimeout(timeoutId);
+      }
+      rl.close();
+    }
+  }
+
+  async promptForInput(prompt: string): Promise<string> {
+    const rl = createInterface({
+      input: process.stdin,
+      output: process.stdout,
+    });
+
+    try {
+      const input = await new Promise<string>((resolve) => {
+        rl.question(prompt, (answer) => {
+          resolve(answer);
+        });
+      });
+
+      return input.trim();
+    } finally {
+      rl.close();
+    }
+  }
+}