appium-ios-remotexpc 0.21.1 → 0.22.0

package/build/src/lib/apple-tv/pairing-protocol/pairing-protocol.js

@@ -1,6 +1,6 @@
-import { logger } from '@appium/support';
 import { randomBytes } from 'node:crypto';
 import { hostname } from 'node:os';
+import { getLogger } from '../../logger.js';
 import { DEFAULT_PAIRING_CONFIG, PairingDataComponentType, } from '../constants.js';
 import { encodeAppleTVDeviceInfo } from '../deviceInfo/index.js';
 import { createEd25519Signature, decryptChaCha20Poly1305, encryptChaCha20Poly1305, generateEd25519KeyPair, hkdf, } from '../encryption/index.js';
@@ -11,11 +11,45 @@ import { PairingStorage } from '../storage/pairing-storage.js';
 import { createPairVerificationData, createSetupManualPairingData, decodeTLV8ToDict, encodeTLV8, } from '../tlv/index.js';
 import { generateHostId } from '../utils/uuid-generator.js';
 import { INFO_TYPE, PAIRING_MESSAGES, PAIRING_STATES } from './constants.js';
-/** Implements the Apple TV pairing protocol including SRP authentication and key exchange */
+const log = getLogger('PairingProtocol');
+/**
+ * Implements the HomeKit Accessory Protocol (HAP) Pair-Setup process for Apple TV.
+ *
+ * Protocol Overview:
+ * This class implements the HAP Pair-Setup protocol, which establishes a secure pairing
+ * between a controller (this client) and an Apple TV accessory. The protocol uses SRP
+ * (Secure Remote Password) authentication to verify a user-provided PIN without transmitting
+ * the PIN itself over the network.
+ *
+ * Message Exchange Flow (M1-M6):
+ * - M1/M2: Initial setup request and SRP challenge (salt + server public key)
+ * - M3/M4: Client sends SRP proof, server validates and responds
+ * - M5/M6: Exchange of long-term public keys and signatures (encrypted)
+ *
+ * After successful pairing, the generated Ed25519 key pair is stored and used for
+ * subsequent Pair-Verify operations to establish encrypted sessions.
+ *
+ * Technical Details:
+ * - Uses SRP-6a protocol for password-authenticated key exchange (RFC 5054)
+ * - Employs Ed25519 for long-term identity keys (RFC 8032)
+ * - Uses ChaCha20-Poly1305 for authenticated encryption (RFC 8439)
+ * - Derives session keys using HKDF (RFC 5869)
+ * - Encodes messages in TLV8 (Type-Length-Value) format
+ *
+ * References:
+ * - HAP Specification: https://developer.apple.com/homekit/ (Apple Developer)
+ * - HAP-NodeJS (community implementation): https://github.com/homebridge/HAP-NodeJS
+ * - SRP Protocol: https://datatracker.ietf.org/doc/html/rfc5054
+ * - Ed25519: https://datatracker.ietf.org/doc/html/rfc8032
+ * - ChaCha20-Poly1305: https://datatracker.ietf.org/doc/html/rfc8439
+ * - HKDF: https://datatracker.ietf.org/doc/html/rfc5869
+ *
+ * @see PairVerificationProtocol for the verification protocol used after pairing
+ * @see SRPClient for SRP authentication implementation
+ */
 export class PairingProtocol {
     networkClient;
     userInput;
-    static log = logger.getLogger('PairingProtocol');
     _sequenceNumber = 0;
     constructor(networkClient, userInput) {
         this.networkClient = networkClient;
@@ -43,7 +77,7 @@ export class PairingProtocol {
             return this.createPairingResult(device, ltpk, ltsk);
         }
         catch (error) {
-            PairingProtocol.log.error('Pairing flow failed:', error);
+            log.error('Pairing flow failed:', error);
             throw error;
         }
     }
@@ -90,7 +124,7 @@ export class PairingProtocol {
         const request = this.createHandshakeRequest();
         await this.networkClient.sendPacket(request);
         await this.networkClient.receiveResponse();
-        PairingProtocol.log.debug('Handshake completed');
+        log.debug('Handshake completed');
     }
     /**
      * Attempts to verify existing pairing credentials with Apple TV
@@ -102,7 +136,7 @@ export class PairingProtocol {
         await this.networkClient.receiveResponse();
         const failedRequest = this.createPairVerifyFailedRequest();
         await this.networkClient.sendPacket(failedRequest);
-        PairingProtocol.log.debug('Pair verification attempt completed');
+        log.debug('Pair verification attempt completed');
     }
     /**
      * Initiates manual pairing setup process with Apple TV
@@ -113,7 +147,7 @@ export class PairingProtocol {
         const request = this.createSetupManualPairingRequest();
         await this.networkClient.sendPacket(request);
         const response = await this.networkClient.receiveResponse();
-        PairingProtocol.log.debug('Manual pairing setup completed');
+        log.debug('Manual pairing setup completed');
         return response;
     }
     /**
@@ -144,7 +178,7 @@ export class PairingProtocol {
         await this.sendSRPProof(srpClient);
         const response = await this.networkClient.receiveResponse();
         this.validateSRPProofResponse(response);
-        PairingProtocol.log.debug('SRP authentication completed');
+        log.debug('SRP authentication completed');
         return srpClient;
     }
     /**
@@ -154,12 +188,12 @@ export class PairingProtocol {
      */
     async receiveM6Completion(decryptKey) {
         const m6Response = await this.networkClient.receiveResponse();
-        PairingProtocol.log.info('M6 Response received');
+        log.info('M6 Response received');
         try {
             this.processM6Response(m6Response, decryptKey);
         }
         catch (error) {
-            PairingProtocol.log.warn('M6 decryption failed - but pairing may still be successful:', error.message);
+            log.warn('M6 decryption failed - but pairing may still be successful:', error.message);
         }
     }
     /**
@@ -443,10 +477,10 @@ export class PairingProtocol {
         const m6DataBase64 = m6Response.message.plain._0.event._0.pairingData._0.data;
         const m6TLVBuffer = Buffer.from(m6DataBase64, 'base64');
         const m6Parsed = decodeTLV8ToDict(m6TLVBuffer);
-        PairingProtocol.log.debug('M6 TLV types received:', Object.keys(m6Parsed).map((k) => `0x${Number(k).toString(16)}`));
+        log.debug('M6 TLV types received:', Object.keys(m6Parsed).map((k) => `0x${Number(k).toString(16)}`));
         const stateData = m6Parsed[PairingDataComponentType.STATE];
         if (stateData && stateData[0] === PAIRING_STATES.M6) {
-            PairingProtocol.log.info('✅ Pairing completed successfully (STATE=0x06)');
+            log.info('✅ Pairing completed successfully (STATE=0x06)');
         }
         const encryptedData = m6Parsed[PairingDataComponentType.ENCRYPTED_DATA];
         if (encryptedData) {
@@ -457,7 +491,7 @@ export class PairingProtocol {
                 nonce,
             });
             const decryptedTLV = decodeTLV8ToDict(decrypted);
-            PairingProtocol.log.debug('M6 decrypted content types:', Object.keys(decryptedTLV));
+            log.debug('M6 decrypted content types:', Object.keys(decryptedTLV));
         }
     }
     /**
@@ -473,7 +507,7 @@ export class PairingProtocol {
             info: Buffer.from(PAIRING_MESSAGES.ENCRYPT_INFO, 'utf8'),
             length: 32,
         });
-        PairingProtocol.log.debug('Derived encryption keys');
+        log.debug('Derived encryption keys');
         return {
             encryptKey: sharedKey,
             decryptKey: sharedKey,

package/build/src/lib/apple-tv/storage/index.d.ts

@@ -1,3 +1,3 @@
 export { PairingStorage } from './pairing-storage.js';
-export type { PairingStorageInterface } from './types.js';
+export type { PairingStorageInterface, PairRecord } from './types.js';
 //# sourceMappingURL=index.d.ts.map

package/build/src/lib/apple-tv/storage/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/lib/apple-tv/storage/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,YAAY,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/lib/apple-tv/storage/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,YAAY,EAAE,uBAAuB,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC"}

package/build/src/lib/apple-tv/storage/pairing-storage.d.ts

@@ -1,12 +1,15 @@
 import type { PairingConfig } from '../types.js';
-import type { PairingStorageInterface } from './types.js';
+import type { PairRecord, PairingStorageInterface } from './types.js';
 /** Manages persistent storage of pairing credentials as plist files */
 export declare class PairingStorage implements PairingStorageInterface {
     private readonly config;
     private readonly log;
     private readonly box;
+    private strongboxDir?;
     constructor(config: PairingConfig);
     save(deviceId: string, ltpk: Buffer, ltsk: Buffer, remoteUnlockHostKey?: string): Promise<string>;
+    load(deviceId: string): Promise<PairRecord | null>;
+    getAvailableDeviceIds(): Promise<string[]>;
     private createPlistContent;
 }
 //# sourceMappingURL=pairing-storage.d.ts.map

package/build/src/lib/apple-tv/storage/pairing-storage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pairing-storage.d.ts","sourceRoot":"","sources":["../../../../../src/lib/apple-tv/storage/pairing-storage.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAE1D,uEAAuE;AACvE,qBAAa,cAAe,YAAW,uBAAuB;IAIhD,OAAO,CAAC,QAAQ,CAAC,MAAM;IAHnC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAsC;IAC1D,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC;gBAEQ,MAAM,EAAE,aAAa;IAI5C,IAAI,CACR,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,mBAAmB,SAAK,GACvB,OAAO,CAAC,MAAM,CAAC;IAyBlB,OAAO,CAAC,kBAAkB;CAW3B"}
+{"version":3,"file":"pairing-storage.d.ts","sourceRoot":"","sources":["../../../../../src/lib/apple-tv/storage/pairing-storage.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,KAAK,EAAE,UAAU,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAEtE,uEAAuE;AACvE,qBAAa,cAAe,YAAW,uBAAuB;IAKhD,OAAO,CAAC,QAAQ,CAAC,MAAM;IAJnC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAA+B;IACnD,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC;IACrB,OAAO,CAAC,YAAY,CAAC,CAAS;gBAED,MAAM,EAAE,aAAa;IAI5C,IAAI,CACR,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,mBAAmB,SAAK,GACvB,OAAO,CAAC,MAAM,CAAC;IAyBZ,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAwClD,qBAAqB,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAwBhD,OAAO,CAAC,kBAAkB;CAW3B"}

package/build/src/lib/apple-tv/storage/pairing-storage.js

@@ -1,20 +1,24 @@
 import { strongbox } from '@appium/strongbox';
-import { logger } from '@appium/support';
+import { readdir } from 'node:fs/promises';
+import { dirname } from 'node:path';
 import { STRONGBOX_CONTAINER_NAME } from '../../../constants.js';
-import { createXmlPlist } from '../../plist/index.js';
+import { getLogger } from '../../logger.js';
+import { createXmlPlist, parseXmlPlist } from '../../plist/index.js';
+import { APPLETV_PAIRING_PREFIX } from '../constants.js';
 import { PairingError } from '../errors.js';
 /** Manages persistent storage of pairing credentials as plist files */
 export class PairingStorage {
     config;
-    log = logger.getLogger('PairingStorage');
+    log = getLogger('PairingStorage');
     box;
+    strongboxDir;
     constructor(config) {
         this.config = config;
         this.box = strongbox(STRONGBOX_CONTAINER_NAME);
     }
     async save(deviceId, ltpk, ltsk, remoteUnlockHostKey = '') {
         try {
-            const itemName = `appletv_pairing_${deviceId}`;
+            const itemName = `${APPLETV_PAIRING_PREFIX}${deviceId}`;
             const plistContent = this.createPlistContent(ltpk, ltsk, remoteUnlockHostKey);
             const item = await this.box.createItemWithValue(itemName, plistContent);
             const itemPath = item.id;
@@ -26,6 +30,57 @@ export class PairingStorage {
             throw new PairingError('Failed to save pairing record', 'SAVE_ERROR', error);
         }
     }
+    async load(deviceId) {
+        const itemName = `${APPLETV_PAIRING_PREFIX}${deviceId}`;
+        try {
+            const item = this.box.getItem(itemName) ?? (await this.box.createItem(itemName));
+            const pairingData = await item.read();
+            if (!pairingData) {
+                this.log.debug(`No pair record found for device ${deviceId}`);
+                return null;
+            }
+            const parsed = parseXmlPlist(pairingData);
+            if (!parsed.private_key || !parsed.public_key) {
+                throw new Error('Could not parse pairing record keys');
+            }
+            const privateKey = Buffer.isBuffer(parsed.private_key)
+                ? parsed.private_key
+                : Buffer.from(parsed.private_key, 'base64');
+            const publicKey = Buffer.isBuffer(parsed.public_key)
+                ? parsed.public_key
+                : Buffer.from(parsed.public_key, 'base64');
+            this.log.debug(`Loaded pair record for ${deviceId}`);
+            return {
+                privateKey,
+                publicKey,
+                remoteUnlockHostKey: parsed.remote_unlock_host_key || '',
+            };
+        }
+        catch (error) {
+            this.log.error(`Failed to load pair record for ${deviceId}:`, error);
+            return null;
+        }
+    }
+    async getAvailableDeviceIds() {
+        try {
+            if (!this.strongboxDir) {
+                const dummyItem = await this.box.createItem('_temp');
+                this.strongboxDir = dirname(dummyItem.id);
+                // Clean up the temporary item after extracting the directory path
+                await dummyItem.clear();
+            }
+            const files = await readdir(this.strongboxDir);
+            const deviceIds = files
+                .filter((file) => file.startsWith(APPLETV_PAIRING_PREFIX))
+                .map((file) => file.replace(APPLETV_PAIRING_PREFIX, ''));
+            this.log.debug(`Found ${deviceIds.length} pair record(s): ${deviceIds.join(', ')}`);
+            return deviceIds;
+        }
+        catch (error) {
+            this.log.debug('Error getting available device IDs:', error);
+            return [];
+        }
+    }
     createPlistContent(publicKey, privateKey, remoteUnlockHostKey) {
         return createXmlPlist({
             private_key: privateKey,

package/build/src/lib/apple-tv/storage/types.d.ts

@@ -1,5 +1,11 @@
-/** Interface for storing pairing credentials to disk */
+export interface PairRecord {
+    publicKey: Buffer;
+    privateKey: Buffer;
+    remoteUnlockHostKey: string;
+}
 export interface PairingStorageInterface {
     save(deviceId: string, ltpk: Buffer, ltsk: Buffer, remoteUnlockHostKey?: string): Promise<string>;
+    load(deviceId: string): Promise<PairRecord | null>;
+    getAvailableDeviceIds(): Promise<string[]>;
 }
 //# sourceMappingURL=types.d.ts.map

package/build/src/lib/apple-tv/storage/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../../src/lib/apple-tv/storage/types.ts"],"names":[],"mappings":"AAAA,wDAAwD;AACxD,MAAM,WAAW,uBAAuB;IACtC,IAAI,CACF,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,mBAAmB,CAAC,EAAE,MAAM,GAC3B,OAAO,CAAC,MAAM,CAAC,CAAC;CACpB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../../src/lib/apple-tv/storage/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,UAAU;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,mBAAmB,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,uBAAuB;IACtC,IAAI,CACF,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,mBAAmB,CAAC,EAAE,MAAM,GAC3B,OAAO,CAAC,MAAM,CAAC,CAAC;IACnB,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAAC;IACnD,qBAAqB,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;CAC5C"}

package/build/src/lib/apple-tv/tunnel/index.d.ts

@@ -0,0 +1,3 @@
+export { TunnelService, AppleTVTunnelService } from './tunnel-service.js';
+export type { TcpListenerInfo } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/build/src/lib/apple-tv/tunnel/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/lib/apple-tv/tunnel/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC1E,YAAY,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC"}

package/build/src/lib/apple-tv/tunnel/index.js

@@ -0,0 +1 @@
+export { TunnelService, AppleTVTunnelService } from './tunnel-service.js';

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

@@ -0,0 +1,57 @@
+import * as tls from 'node:tls';
+import type { AppleTVDevice } from '../../bonjour/bonjour-discovery.js';
+import type { NetworkClientInterface } from '../network/types.js';
+import type { VerificationKeys } from '../pairing-protocol/pair-verification-protocol.js';
+import type { TcpListenerInfo } from './types.js';
+export declare class TunnelService {
+    private readonly networkClient;
+    private readonly keys;
+    private sequenceNumber;
+    private static readonly log;
+    private encryptedSequenceNumber;
+    constructor(networkClient: NetworkClientInterface, keys: VerificationKeys, sequenceNumber: number);
+    createTcpListener(): Promise<TcpListenerInfo>;
+    createTlsPskConnection(hostname: string, port: number): Promise<tls.TLSSocket>;
+    getSequenceNumber(): number;
+}
+/**
+ * High-level service for establishing Apple TV tunnels.
+ * Orchestrates device discovery, pairing verification, and tunnel creation.
+ */
+export declare class AppleTVTunnelService {
+    private readonly networkClient;
+    private readonly storage;
+    private sequenceNumber;
+    constructor();
+    disconnect(): void;
+    startTunnel(deviceId?: string, specificDeviceIdentifier?: string): Promise<{
+        socket: tls.TLSSocket;
+        device: AppleTVDevice;
+    }>;
+    /**
+     * Logs information about discovered devices
+     */
+    private logDiscoveredDevices;
+    /**
+     * Selects devices to process based on the specific device identifier
+     */
+    private selectDevicesToProcess;
+    /**
+     * Validates pair records and returns the list of identifiers to try
+     */
+    private validateAndGetPairRecords;
+    /**
+     * Attempts to establish a connection with a device using a specific pair record
+     */
+    private attemptDeviceConnection;
+    /**
+     * Logs a summary of all failed connection attempts
+     */
+    private logFailureSummary;
+    private discoverDevices;
+    private performHandshake;
+    private performPairVerification;
+    private createTcpListener;
+    private createTlsPskConnection;
+}
+//# sourceMappingURL=tunnel-service.d.ts.map

package/build/src/lib/apple-tv/tunnel/tunnel-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tunnel-service.d.ts","sourceRoot":"","sources":["../../../../../src/lib/apple-tv/tunnel/tunnel-service.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,GAAG,MAAM,UAAU,CAAC;AAEhC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oCAAoC,CAAC;AAUxE,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAElE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mDAAmD,CAAC;AAG1F,OAAO,KAAK,EAAE,eAAe,EAA2B,MAAM,YAAY,CAAC;AAI3E,qBAAa,aAAa;IAKtB,OAAO,CAAC,QAAQ,CAAC,aAAa;IAC9B,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,cAAc;IANxB,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAA8B;IACzD,OAAO,CAAC,uBAAuB,CAAK;gBAGjB,aAAa,EAAE,sBAAsB,EACrC,IAAI,EAAE,gBAAgB,EAC/B,cAAc,EAAE,MAAM;IAG1B,iBAAiB,IAAI,OAAO,CAAC,eAAe,CAAC;IAoF7C,sBAAsB,CAC1B,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC;IAoEzB,iBAAiB,IAAI,MAAM;CAG5B;AAED;;;GAGG;AACH,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAgB;IAC9C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAiB;IACzC,OAAO,CAAC,cAAc,CAAK;;IAO3B,UAAU,IAAI,IAAI;IAIZ,WAAW,CACf,QAAQ,CAAC,EAAE,MAAM,EACjB,wBAAwB,CAAC,EAAE,MAAM,GAChC,OAAO,CAAC;QAAE,MAAM,EAAE,GAAG,CAAC,SAAS,CAAC;QAAC,MAAM,EAAE,aAAa,CAAA;KAAE,CAAC;IAiD5D;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAkB5B;;OAEG;IACH,OAAO,CAAC,sBAAsB;IAgC9B;;OAEG;YACW,yBAAyB;IAgBvC;;OAEG;YACW,uBAAuB;IA2DrC;;OAEG;IACH,OAAO,CAAC,iBAAiB;YAWX,eAAe;YAoDf,gBAAgB;YA4BhB,uBAAuB;YAmBvB,iBAAiB;YAiBjB,sBAAsB;CAYrC"}