appium-ios-remotexpc 0.21.2 → 0.22.0

package/scripts/start-appletv-tunnel.ts

@@ -0,0 +1,178 @@
+#!/usr/bin/env tsx
+import * as tls from 'node:tls';
+
+import { PacketStreamServer, TunnelManager } from '../src/index.js';
+import type { TunnelRegistry } from '../src/index.js';
+import { AppleTVTunnelService } from '../src/lib/apple-tv/tunnel/index.js';
+import type { AppleTVDevice } from '../src/lib/bonjour/bonjour-discovery.js';
+import { getLogger } from '../src/lib/logger.js';
+import type { TunnelConnection } from '../src/lib/tunnel/index.js';
+import {
+  DEFAULT_TUNNEL_REGISTRY_PORT,
+  startTunnelRegistryServer,
+} from '../src/lib/tunnel/tunnel-registry-server.js';
+
+const log = getLogger('WiFiTunnel');
+const PACKET_STREAM_PORT = 50100;
+
+async function main(): Promise<void> {
+  const args = process.argv.slice(2);
+  const specificDeviceIdentifier = args.find((arg) => !arg.startsWith('-'));
+
+  if (specificDeviceIdentifier) {
+    log.info(
+      `Starting Apple TV tunnel for specific device identifier: ${specificDeviceIdentifier}`,
+    );
+  } else {
+    log.info('Starting Apple TV tunnel (will try all discovered devices)');
+  }
+
+  const tunnelService = new AppleTVTunnelService();
+  let tunnel: TunnelConnection | null = null;
+  let tlsSocket: tls.TLSSocket | null = null;
+  let deviceInfo: AppleTVDevice | null = null;
+  let packetStreamServer: PacketStreamServer | null = null;
+
+  const cleanup = async (signal: string): Promise<void> => {
+    log.warn(`\nCleaning up (${signal})...`);
+
+    try {
+      // Close packet stream server first
+      if (packetStreamServer) {
+        log.info('Closing packet stream server...');
+        await packetStreamServer.stop();
+        packetStreamServer = null;
+      }
+
+      if (tunnel && typeof tunnel.closer === 'function') {
+        log.info('Closing tunnel...');
+        await tunnel.closer();
+      }
+
+      if (tlsSocket && !tlsSocket.destroyed) {
+        log.info('Closing TLS-PSK connection...');
+        tlsSocket.destroy();
+      }
+
+      tunnelService.disconnect();
+
+      log.info('Cleanup completed.');
+    } catch (err) {
+      log.error('Error during cleanup:', err);
+    }
+  };
+
+  process.on('SIGINT', async () => {
+    await cleanup('SIGINT (Ctrl+C)');
+    process.exit(0);
+  });
+  process.on('SIGTERM', async () => {
+    await cleanup('SIGTERM');
+    process.exit(0);
+  });
+  process.on('SIGHUP', async () => {
+    await cleanup('SIGHUP');
+    process.exit(0);
+  });
+
+  process.on('uncaughtException', async (error) => {
+    log.error('Uncaught Exception:', error);
+    await cleanup('Uncaught Exception');
+  });
+
+  process.on('unhandledRejection', async (reason, promise) => {
+    log.error('Unhandled Rejection at:', promise, 'reason:', reason);
+    await cleanup('Unhandled Rejection');
+  });
+
+  try {
+    log.info('Starting Apple TV tunnel...');
+    const result = await tunnelService.startTunnel(
+      undefined,
+      specificDeviceIdentifier,
+    );
+    tlsSocket = result.socket;
+    deviceInfo = result.device;
+
+    if (!tlsSocket) {
+      throw new Error('TLS-PSK socket not established');
+    }
+
+    log.info('Creating tunnel with TunnelManager...');
+    tunnel = await TunnelManager.getTunnel(tlsSocket);
+
+    // Start packet stream server (same as iPhone tunnel)
+    let packetStreamPort = 0;
+    try {
+      packetStreamServer = new PacketStreamServer(PACKET_STREAM_PORT);
+      await packetStreamServer.start();
+
+      // Attach packet consumer to tunnel to receive packet data
+      const consumer = packetStreamServer.getPacketConsumer();
+      if (consumer && tunnel.addPacketConsumer) {
+        tunnel.addPacketConsumer(consumer);
+        log.info(`Packet stream server started on port ${PACKET_STREAM_PORT}`);
+        packetStreamPort = PACKET_STREAM_PORT;
+      } else {
+        log.warn('Failed to attach packet consumer to tunnel');
+      }
+    } catch (err) {
+      log.warn(`Failed to start packet stream server: ${err}`);
+    }
+
+    const now = Date.now();
+    const nowISOString = new Date().toISOString();
+
+    const registry: TunnelRegistry = {
+      tunnels: {
+        [deviceInfo.identifier]: {
+          udid: deviceInfo.identifier,
+          deviceId: 0,
+          address: tunnel.Address,
+          rsdPort: tunnel.RsdPort ?? 0,
+          packetStreamPort,
+          connectionType: 'WiFi',
+          productId: 0,
+          createdAt: now,
+          lastUpdated: now,
+        },
+      },
+      metadata: {
+        lastUpdated: nowISOString,
+        totalTunnels: 1,
+        activeTunnels: 1,
+      },
+    };
+
+    await startTunnelRegistryServer(registry);
+
+    log.info('=== TUNNEL ESTABLISHED ===');
+    log.info(`Tunnel Address: ${tunnel.Address}`);
+    log.info(`Tunnel RSD Port: ${tunnel.RsdPort}`);
+    log.info(`Packet Stream Port: ${packetStreamPort}`);
+    log.info('==========================');
+
+    log.info('\n📁 Tunnel registry API:');
+    log.info(
+      `   http://localhost:${DEFAULT_TUNNEL_REGISTRY_PORT}/remotexpc/tunnels`,
+    );
+    log.info('   - GET /remotexpc/tunnels - List all tunnels');
+    log.info(
+      `   - GET /remotexpc/tunnels/${deviceInfo.identifier} - Get tunnel by identifier`,
+    );
+    log.info('   - GET /remotexpc/tunnels/metadata - Get registry metadata');
+
+    log.info('\n✅ Apple TV tunnel is ready!');
+    log.info(`Use: --rsd ${tunnel.Address} ${tunnel.RsdPort}`);
+    log.info('\nPress Ctrl+C to close the tunnel and exit.');
+
+    process.stdin.resume();
+  } catch (error) {
+    log.error('Tunnel failed:', error);
+    throw error;
+  } finally {
+    await cleanup('Shutdown');
+  }
+}
+
+main();

package/scripts/test-tunnel-creation.ts

@@ -8,14 +8,16 @@ import type { ConnectionOptions } from 'tls';
 
 import {
   PacketStreamServer,
-  SocketInfo,
   TunnelManager,
   createLockdownServiceByUDID,
   createUsbmux,
   startCoreDeviceProxy,
-  TunnelRegistry,
 } from '../src/index.js';
-import { startTunnelRegistryServer } from '../src/lib/tunnel/tunnel-registry-server.js';
+import type { SocketInfo, TunnelRegistry } from '../src/index.js';
+import {
+  DEFAULT_TUNNEL_REGISTRY_PORT,
+  startTunnelRegistryServer,
+} from '../src/lib/tunnel/tunnel-registry-server.js';
 import type { Device } from '../src/lib/usbmux/index.js';
 
 const log = logger.getLogger('TunnelCreation');
@@ -27,7 +29,7 @@ async function updateTunnelRegistry(
 ): Promise<TunnelRegistry> {
   const now = Date.now();
   const nowISOString = new Date().toISOString();
-  
+
   // Initialize registry if it doesn't exist
   const registry: TunnelRegistry = {
     tunnels: {},
@@ -35,7 +37,7 @@ async function updateTunnelRegistry(
       lastUpdated: nowISOString,
       totalTunnels: 0,
       activeTunnels: 0,
-    }
+    },
   };
 
   // Update tunnels
@@ -47,7 +49,7 @@ async function updateTunnelRegistry(
         deviceId: result.device.DeviceID,
         address: result.tunnel.Address,
         rsdPort: result.tunnel.RsdPort ?? 0,
-        packetStreamPort: result.packetStreamPort,
+        packetStreamPort: result.packetStreamPort ?? 0,
         connectionType: result.device.Properties.ConnectionType,
         productId: result.device.Properties.ProductID,
         createdAt: registry.tunnels[udid]?.createdAt ?? now,
@@ -86,7 +88,7 @@ let PACKET_STREAM_BASE_PORT = 50000;
  */
 function setupCleanupHandlers(): void {
   const cleanup = async (signal: string) => {
-    log.warn(`\nReceived ${signal}. Cleaning up...`);
+    log.warn(`\nCleaning up (${signal})...`);
 
     // Close all packet stream servers
     if (packetStreamServers.size > 0) {
@@ -106,26 +108,32 @@ function setupCleanupHandlers(): void {
       packetStreamServers.clear();
     }
 
-    log.info('Cleanup completed. Exiting...');
-    process.exit(0);
+    log.info('Cleanup completed.');
   };
 
   // Handle various termination signals
-  process.on('SIGINT', () => cleanup('SIGINT (Ctrl+C)'));
-  process.on('SIGTERM', () => cleanup('SIGTERM'));
-  process.on('SIGHUP', () => cleanup('SIGHUP'));
+  process.on('SIGINT', async () => {
+    await cleanup('SIGINT (Ctrl+C)');
+    process.exit(0);
+  });
+  process.on('SIGTERM', async () => {
+    await cleanup('SIGTERM');
+    process.exit(0);
+  });
+  process.on('SIGHUP', async () => {
+    await cleanup('SIGHUP');
+    process.exit(0);
+  });
 
   // Handle uncaught exceptions and unhandled rejections
   process.on('uncaughtException', async (error) => {
     log.error('Uncaught Exception:', error);
     await cleanup('Uncaught Exception');
-    process.exit(1);
   });
 
   process.on('unhandledRejection', async (reason, promise) => {
     log.error('Unhandled Rejection at:', promise, 'reason:', reason);
     await cleanup('Unhandled Rejection');
-    process.exit(1);
   });
 }
 
@@ -225,7 +233,7 @@ async function createTunnelForDevice(
         },
         packetStreamPort,
         success: true,
-        socket
+        socket,
       };
     } catch (err) {
       log.warn(`Could not add device to info server: ${err}`);
@@ -356,23 +364,24 @@ async function main(): Promise<void> {
       log.info('   - GET /remotexpc/tunnels/metadata - Get registry metadata');
 
       log.info('\n💡 Example usage:');
-      log.info('   curl http://localhost:4723/remotexpc/tunnels');
-      log.info('   curl http://localhost:4723/remotexpc/tunnels/metadata');
+      log.info(
+        `   curl http://localhost:${DEFAULT_TUNNEL_REGISTRY_PORT}/remotexpc/tunnels`,
+      );
+      log.info(
+        `   curl http://localhost:${DEFAULT_TUNNEL_REGISTRY_PORT}/remotexpc/tunnels/metadata`,
+      );
       if (successful.length > 0) {
         const firstUdid = successful[0].device.Properties.SerialNumber;
         log.info(
-          `   curl http://localhost:4723/remotexpc/tunnels/${firstUdid}`,
+          `   curl http://localhost:${DEFAULT_TUNNEL_REGISTRY_PORT}/remotexpc/tunnels/${firstUdid}`,
         );
       }
     }
   } catch (error) {
     log.error(`Error during tunnel creation test: ${error}`);
-    process.exit(1);
+    throw error;
   }
 }
 
 // Run the main function
-main().catch(async (error) => {
-  log.error(`Fatal error: ${error}`);
-  process.exit(1);
-});
+main();

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

@@ -1,10 +1,18 @@
 // Default configuration values for Apple TV pairing behavior
+// These can be overridden via environment variables:
+// - APPLETV_TIMEOUT: Network operation timeout in milliseconds (default: 30000)
+// - APPLETV_DISCOVERY_TIMEOUT: Device discovery timeout in milliseconds (default: 10000)
+//   10 seconds provides reliable Apple TV discovery via mDNS/Bonjour across various network conditions
+// - APPLETV_MAX_RETRIES: Maximum retry attempts (default: 3)
 export const DEFAULT_PAIRING_CONFIG = {
-  timeout: 30000,
-  discoveryTimeout: 5000,
-  maxRetries: 3,
+  timeout: Number(process.env.APPLETV_TIMEOUT) || 30000,
+  discoveryTimeout: Number(process.env.APPLETV_DISCOVERY_TIMEOUT) || 10000,
+  maxRetries: Number(process.env.APPLETV_MAX_RETRIES) || 3,
 } as const;
 
+// Prefix used for Apple TV pairing record storage identifiers
+export const APPLETV_PAIRING_PREFIX = 'appletv_pairing_';
+
 // TLV8 component type identifiers used in pairing data exchange
 export const PairingDataComponentType = {
   METHOD: 0x00,

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

@@ -1,15 +1,14 @@
-import { logger } from '@appium/support';
-
 import {
   type AppleTVDevice,
   BonjourDiscovery,
 } from '../../bonjour/bonjour-discovery.js';
+import { getLogger } from '../../logger.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');
+  private readonly log = getLogger('DeviceDiscoveryService');
 
   constructor(private readonly config: PairingConfig) {}
 

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

@@ -8,4 +8,10 @@ export {
 
 export { generateEd25519KeyPair, createEd25519Signature } from './ed25519.js';
 
+export {
+  generateX25519KeyPair,
+  performX25519DiffieHellman,
+  type X25519KeyPair,
+} from './x25519.js';
+
 export { hkdf, type HKDFParams } from './hkdf.js';

package/src/lib/apple-tv/encryption/x25519.ts

@@ -0,0 +1,79 @@
+import {
+  type KeyObject,
+  createPublicKey,
+  diffieHellman,
+  generateKeyPairSync,
+} from 'node:crypto';
+
+import { getLogger } from '../../logger.js';
+import { CryptographyError } from '../errors.js';
+
+const log = getLogger('X25519');
+
+const X25519_PUBLIC_KEY_LENGTH = 32;
+const X25519_SPKI_PREFIX = Buffer.from([
+  0x30, 0x2a, 0x30, 0x05, 0x06, 0x03, 0x2b, 0x65, 0x6e, 0x03, 0x21, 0x00,
+]);
+
+export interface X25519KeyPair {
+  publicKey: Buffer;
+  privateKey: KeyObject;
+}
+
+export function generateX25519KeyPair(): X25519KeyPair {
+  try {
+    const { publicKey, privateKey } = generateKeyPairSync('x25519');
+
+    const publicKeyDer = publicKey.export({
+      type: 'spki',
+      format: 'der',
+    }) as Buffer;
+    const publicKeyBytes = publicKeyDer.subarray(-X25519_PUBLIC_KEY_LENGTH);
+
+    return {
+      publicKey: publicKeyBytes,
+      privateKey,
+    };
+  } catch (error) {
+    log.error('Failed to generate X25519 key pair:', error);
+    const message = error instanceof Error ? error.message : String(error);
+    throw new CryptographyError(
+      `Failed to generate X25519 key pair: ${message}`,
+    );
+  }
+}
+
+export function performX25519DiffieHellman(
+  privateKey: KeyObject,
+  devicePublicKey: Buffer,
+): Buffer {
+  if (!devicePublicKey || devicePublicKey.length !== X25519_PUBLIC_KEY_LENGTH) {
+    throw new CryptographyError(
+      `Device public key must be ${X25519_PUBLIC_KEY_LENGTH} bytes`,
+    );
+  }
+
+  try {
+    const devicePublicKeySpki = Buffer.concat([
+      X25519_SPKI_PREFIX,
+      devicePublicKey,
+    ]);
+
+    const publicKeyObject = createPublicKey({
+      key: devicePublicKeySpki,
+      format: 'der',
+      type: 'spki',
+    });
+
+    return diffieHellman({
+      privateKey,
+      publicKey: publicKeyObject,
+    });
+  } catch (error) {
+    log.error('Failed to perform X25519 Diffie-Hellman:', error);
+    const message = error instanceof Error ? error.message : String(error);
+    throw new CryptographyError(
+      `Failed to perform X25519 Diffie-Hellman: ${message}`,
+    );
+  }
+}

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

@@ -20,5 +20,6 @@ export * from './srp/index.js';
 export * from './network/index.js';
 export * from './pairing-protocol/index.js';
 export * from './storage/index.js';
+export * from './tunnel/index.js';
 export * from './discovery/index.js';
 export * from './pairing/index.js';

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

@@ -1,12 +1,12 @@
-import { logger } from '@appium/support';
 import * as net from 'node:net';
 
+import { getLogger } from '../../logger.js';
 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');
+const log = getLogger('NetworkClient');
 
 /** Handles TCP socket communication with Apple TV devices */
 export class NetworkClient implements NetworkClientInterface {

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

@@ -1,13 +1,13 @@
-import { logger } from '@appium/support';
 import { createInterface } from 'node:readline';
 
+import { getLogger } from '../../logger.js';
 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');
+  private readonly log = getLogger('UserInputService');
 
   async promptForPIN(): Promise<string> {
     const rl = createInterface({

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

@@ -15,5 +15,34 @@ export const PAIRING_MESSAGES = {
   M6_NONCE: 'PS-Msg06',
 } as const;
 
+export const PAIR_VERIFY_MESSAGES = {
+  ENCRYPT_SALT: 'Pair-Verify-Encrypt-Salt',
+  ENCRYPT_INFO: 'Pair-Verify-Encrypt-Info',
+  STATE_03_NONCE: 'PV-Msg03',
+} as const;
+
+export const PAIR_VERIFY_STATES = {
+  STATE_01: 0x01,
+  STATE_02: 0x02,
+  STATE_03: 0x03,
+  STATE_04: 0x04,
+} as const;
+
+export const ENCRYPTION_MESSAGES = {
+  CLIENT_ENCRYPT: 'ClientEncrypt-main',
+  SERVER_ENCRYPT: 'ServerEncrypt-main',
+} as const;
+
+/** Error descriptions for pair verification STATE=4 errors */
+export const PAIR_VERIFY_ERROR_DESCRIPTIONS: Record<number, string> = {
+  1: 'Unknown error',
+  2: 'Authentication failed - invalid pair record',
+  3: 'Backoff - too many attempts',
+  4: 'Max peers - device has too many connections',
+  5: 'Max tries exceeded',
+  6: 'Service unavailable',
+  7: 'Device busy',
+} as const;
+
 /** TLV type for device info */
 export const INFO_TYPE = 0x11;

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

@@ -1,5 +1,16 @@
 export { PairingProtocol } from './pairing-protocol.js';
-export { PAIRING_STATES, PAIRING_MESSAGES, INFO_TYPE } from './constants.js';
+export {
+  PairVerificationProtocol,
+  type VerificationKeys,
+} from './pair-verification-protocol.js';
+export {
+  PAIRING_STATES,
+  PAIRING_MESSAGES,
+  INFO_TYPE,
+  PAIR_VERIFY_MESSAGES,
+  PAIR_VERIFY_STATES,
+  ENCRYPTION_MESSAGES,
+} from './constants.js';
 export type {
   EncryptionKeys,
   PairingRequest,