appium-ios-remotexpc 0.21.2 → 0.22.0

package/src/lib/apple-tv/pairing-protocol/pair-verification-protocol.ts

@@ -0,0 +1,329 @@
+import { type KeyObject } from 'node:crypto';
+import { hostname } from 'node:os';
+
+import { getLogger } from '../../logger.js';
+import { PairingDataComponentType } from '../constants.js';
+import {
+  createEd25519Signature,
+  encryptChaCha20Poly1305,
+  generateX25519KeyPair,
+  hkdf,
+  performX25519DiffieHellman,
+} from '../encryption/index.js';
+import { PairingError } from '../errors.js';
+import type { NetworkClientInterface } from '../network/types.js';
+import type { PairRecord } from '../storage/types.js';
+import { decodeTLV8ToDict, encodeTLV8 } from '../tlv/index.js';
+import { generateHostId } from '../utils/uuid-generator.js';
+import {
+  ENCRYPTION_MESSAGES,
+  PAIR_VERIFY_ERROR_DESCRIPTIONS,
+  PAIR_VERIFY_MESSAGES,
+  PAIR_VERIFY_STATES,
+} from './constants.js';
+import type { PairingRequest } from './types.js';
+
+const log = getLogger('PairVerificationProtocol');
+
+/**
+ * Implements the HomeKit Accessory Protocol (HAP) Pair-Verify process for Apple TV.
+ *
+ * Protocol Overview:
+ * This class implements the HAP Pair-Verify protocol, which establishes an encrypted
+ * session between a previously paired controller (this client) and an Apple TV accessory.
+ * Unlike Pair-Setup, Pair-Verify uses existing long-term keys to authenticate both parties
+ * and derive session-specific encryption keys without requiring user interaction.
+ *
+ * State Machine Flow (4 states):
+ * - STATE=1: Client sends ephemeral X25519 public key to device
+ * - STATE=2: Device responds with its ephemeral X25519 public key and encrypted proof
+ * - STATE=3: Client sends encrypted signature proving identity using Ed25519 private key
+ * - STATE=4: Device confirms verification success or returns error
+ *
+ * After successful verification, both parties derive shared session keys for encrypting
+ * all subsequent communication during this session.
+ *
+ * Technical Details:
+ * - Uses X25519 Elliptic Curve Diffie-Hellman for ephemeral key exchange (RFC 7748)
+ * - Employs Ed25519 signatures for authentication using long-term keys (RFC 8032)
+ * - Uses ChaCha20-Poly1305 for authenticated encryption (RFC 8439)
+ * - Derives session keys using HKDF with protocol-specific salt/info (RFC 5869)
+ * - Encodes messages in TLV8 (Type-Length-Value) format
+ *
+ * Security Properties:
+ * - Perfect Forward Secrecy: Each session uses unique ephemeral keys
+ * - Mutual Authentication: Both client and device prove their identities
+ * - Replay Protection: Ephemeral keys prevent replay attacks
+ *
+ * References:
+ * - HAP Specification: https://developer.apple.com/homekit/ (Apple Developer)
+ * - HAP-NodeJS (community implementation): https://github.com/homebridge/HAP-NodeJS
+ * - X25519 ECDH: https://datatracker.ietf.org/doc/html/rfc7748
+ * - Ed25519 Signatures: 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 PairingProtocol for the initial pairing process that generates the long-term keys
+ * @see PairRecord for the stored credentials used in verification
+ */
+
+export interface VerificationKeys {
+  encryptionKey: Buffer;
+  clientEncryptionKey: Buffer;
+  serverEncryptionKey: Buffer;
+}
+
+export class PairVerificationProtocol {
+  private readonly hostIdentifier: string;
+  private sequenceNumber: number = 0;
+
+  constructor(private readonly networkClient: NetworkClientInterface) {
+    this.hostIdentifier = generateHostId(hostname());
+  }
+
+  async verify(
+    pairRecord: PairRecord,
+    deviceId: string,
+  ): Promise<VerificationKeys> {
+    log.debug('Starting pair verification (4-step process)');
+
+    const { publicKey, privateKey } = generateX25519KeyPair();
+
+    log.debug('  - STATE=1: Send X25519 public key to device');
+    await this.sendState1(publicKey);
+
+    const devicePublicKey = await this.processState2Response();
+
+    const sharedSecret = this.computeSharedSecret(privateKey, devicePublicKey);
+    const pairVerifyKey = this.derivePairVerifyKey(sharedSecret);
+
+    log.debug(
+      '  - STATE=3: Send encrypted signature using Ed25519 private key from pair record',
+    );
+    log.debug(`    Using pair record: ${deviceId}`);
+
+    await this.sendState3(
+      pairRecord,
+      publicKey,
+      devicePublicKey,
+      pairVerifyKey,
+    );
+
+    await this.validateState4Response();
+
+    log.debug('  - STATE=4: Receive verification success from device');
+
+    return this.deriveEncryptionKeys(sharedSecret);
+  }
+
+  getSequenceNumber(): number {
+    return this.sequenceNumber;
+  }
+
+  setSequenceNumber(value: number): void {
+    this.sequenceNumber = value;
+  }
+
+  private async processState2Response(): Promise<Buffer> {
+    const state2Response = await this.networkClient.receiveResponse();
+
+    const pairingData =
+      state2Response.message?.plain?._0?.event?._0?.pairingData?._0?.data;
+    if (!pairingData) {
+      throw new PairingError(
+        'No pairing data in STATE=2 response',
+        'STATE_2_NO_DATA',
+      );
+    }
+
+    const tlvData = decodeTLV8ToDict(Buffer.from(pairingData, 'base64'));
+
+    if (tlvData[PairingDataComponentType.ERROR]) {
+      const errorCode = tlvData[PairingDataComponentType.ERROR] as Buffer;
+      const errorDecimal = errorCode[0];
+      log.error(
+        `Device returned error in STATE=2: ${errorCode.toString('hex')} (decimal: ${errorDecimal})`,
+      );
+      throw new PairingError(
+        `Authentication failed at STATE=2 (error: ${errorDecimal})`,
+        'STATE_2_ERROR',
+      );
+    }
+
+    const devicePublicKey = tlvData[PairingDataComponentType.PUBLIC_KEY];
+    if (!devicePublicKey) {
+      throw new PairingError(
+        'No device public key in STATE=2',
+        'STATE_2_NO_PUBLIC_KEY',
+      );
+    }
+
+    log.debug(' - STATE=2: Receive devices X25519 public key + encrypted data');
+
+    return devicePublicKey;
+  }
+
+  private computeSharedSecret(
+    privateKey: KeyObject,
+    devicePublicKey: Buffer,
+  ): Buffer {
+    return performX25519DiffieHellman(privateKey, devicePublicKey);
+  }
+
+  private derivePairVerifyKey(sharedSecret: Buffer): Buffer {
+    return hkdf({
+      ikm: sharedSecret,
+      salt: Buffer.from(PAIR_VERIFY_MESSAGES.ENCRYPT_SALT),
+      info: Buffer.from(PAIR_VERIFY_MESSAGES.ENCRYPT_INFO),
+      length: 32,
+    });
+  }
+
+  private async validateState4Response(): Promise<void> {
+    const state4Response = await this.networkClient.receiveResponse();
+
+    const state4Data =
+      state4Response.message?.plain?._0?.event?._0?.pairingData?._0?.data;
+    if (!state4Data) {
+      return;
+    }
+
+    const state4TLV = decodeTLV8ToDict(Buffer.from(state4Data, 'base64'));
+
+    if (state4TLV[PairingDataComponentType.ERROR]) {
+      const errorCode = state4TLV[PairingDataComponentType.ERROR] as Buffer;
+      const errorDecimal = errorCode[0];
+
+      const errorDescription =
+        PAIR_VERIFY_ERROR_DESCRIPTIONS[errorDecimal] || 'Unknown error';
+
+      log.error(
+        `Device returned error in STATE=4: ${errorCode.toString('hex')} (decimal: ${errorDecimal})`,
+      );
+      log.error(`Error description: ${errorDescription}`);
+      throw new PairingError(
+        `Pair verification failed: ${errorDescription}`,
+        'STATE_4_ERROR',
+      );
+    }
+  }
+
+  private createPairingPayload(
+    data: string,
+    startNewSession: boolean,
+  ): PairingRequest {
+    return {
+      message: {
+        plain: {
+          _0: {
+            event: {
+              _0: {
+                pairingData: {
+                  _0: {
+                    data,
+                    kind: 'verifyManualPairing',
+                    startNewSession,
+                  },
+                },
+              },
+            },
+          },
+        },
+      },
+      originatedBy: 'host',
+      sequenceNumber: this.sequenceNumber++,
+    };
+  }
+
+  private async sendState1(x25519PublicKey: Buffer): Promise<void> {
+    const tlvData = encodeTLV8([
+      {
+        type: PairingDataComponentType.STATE,
+        data: Buffer.from([PAIR_VERIFY_STATES.STATE_01]),
+      },
+      { type: PairingDataComponentType.PUBLIC_KEY, data: x25519PublicKey },
+    ]);
+
+    const payload = this.createPairingPayload(tlvData.toString('base64'), true);
+
+    await this.networkClient.sendPacket(payload);
+  }
+
+  private async sendState3(
+    pairRecord: PairRecord,
+    x25519PublicKey: Buffer,
+    devicePublicKey: Buffer,
+    pairVerifyEncryptionKey: Buffer,
+  ): Promise<void> {
+    const signData = Buffer.concat([
+      x25519PublicKey,
+      Buffer.from(this.hostIdentifier, 'utf8'),
+      devicePublicKey,
+    ]);
+
+    const signature = createEd25519Signature(signData, pairRecord.privateKey);
+
+    const responseTLV = encodeTLV8([
+      {
+        type: PairingDataComponentType.IDENTIFIER,
+        data: Buffer.from(this.hostIdentifier, 'utf8'),
+      },
+      { type: PairingDataComponentType.SIGNATURE, data: signature },
+    ]);
+
+    const nonce = Buffer.concat([
+      Buffer.alloc(4),
+      Buffer.from(PAIR_VERIFY_MESSAGES.STATE_03_NONCE),
+    ]);
+
+    const encryptedResponse = encryptChaCha20Poly1305({
+      plaintext: responseTLV,
+      key: pairVerifyEncryptionKey,
+      nonce,
+    });
+
+    const finalTLV = encodeTLV8([
+      {
+        type: PairingDataComponentType.STATE,
+        data: Buffer.from([PAIR_VERIFY_STATES.STATE_03]),
+      },
+      {
+        type: PairingDataComponentType.ENCRYPTED_DATA,
+        data: encryptedResponse,
+      },
+    ]);
+
+    const payload = this.createPairingPayload(
+      finalTLV.toString('base64'),
+      false,
+    );
+
+    await this.networkClient.sendPacket(payload);
+  }
+
+  private deriveEncryptionKeys(sharedSecret: Buffer): VerificationKeys {
+    log.debug('Deriving main encryption keys');
+
+    const clientEncryptionKey = hkdf({
+      ikm: sharedSecret,
+      salt: null,
+      info: Buffer.from(ENCRYPTION_MESSAGES.CLIENT_ENCRYPT),
+      length: 32,
+    });
+
+    const serverEncryptionKey = hkdf({
+      ikm: sharedSecret,
+      salt: null,
+      info: Buffer.from(ENCRYPTION_MESSAGES.SERVER_ENCRYPT),
+      length: 32,
+    });
+
+    log.debug('Derived client/server encryption keys using HKDF');
+
+    return {
+      encryptionKey: sharedSecret,
+      clientEncryptionKey,
+      serverEncryptionKey,
+    };
+  }
+}

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

@@ -1,8 +1,8 @@
-import { logger } from '@appium/support';
 import { randomBytes } from 'node:crypto';
 import { hostname } from 'node:os';
 
 import type { AppleTVDevice } from '../../bonjour/bonjour-discovery.js';
+import { getLogger } from '../../logger.js';
 import {
   DEFAULT_PAIRING_CONFIG,
   PairingDataComponentType,
@@ -36,9 +36,44 @@ import type {
   UserInputInterface,
 } from './types.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 implements PairingProtocolInterface {
-  private static readonly log = logger.getLogger('PairingProtocol');
   private _sequenceNumber = 0;
 
   constructor(
@@ -81,7 +116,7 @@ export class PairingProtocol implements PairingProtocolInterface {
 
       return this.createPairingResult(device, ltpk, ltsk);
     } catch (error) {
-      PairingProtocol.log.error('Pairing flow failed:', error);
+      log.error('Pairing flow failed:', error);
       throw error;
     }
   }
@@ -136,7 +171,7 @@ export class PairingProtocol implements PairingProtocolInterface {
     const request = this.createHandshakeRequest();
     await this.networkClient.sendPacket(request);
     await this.networkClient.receiveResponse();
-    PairingProtocol.log.debug('Handshake completed');
+    log.debug('Handshake completed');
   }
 
   /**
@@ -150,7 +185,7 @@ export class PairingProtocol implements PairingProtocolInterface {
 
     const failedRequest = this.createPairVerifyFailedRequest();
     await this.networkClient.sendPacket(failedRequest);
-    PairingProtocol.log.debug('Pair verification attempt completed');
+    log.debug('Pair verification attempt completed');
   }
 
   /**
@@ -162,7 +197,7 @@ export class PairingProtocol implements PairingProtocolInterface {
     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;
   }
 
@@ -201,7 +236,7 @@ export class PairingProtocol implements PairingProtocolInterface {
     const response = await this.networkClient.receiveResponse();
     this.validateSRPProofResponse(response);
 
-    PairingProtocol.log.debug('SRP authentication completed');
+    log.debug('SRP authentication completed');
     return srpClient;
   }
 
@@ -212,12 +247,12 @@ export class PairingProtocol implements PairingProtocolInterface {
    */
   private async receiveM6Completion(decryptKey: Buffer): Promise<void> {
     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(
+      log.warn(
         'M6 decryption failed - but pairing may still be successful:',
         (error as Error).message,
       );
@@ -568,16 +603,14 @@ export class PairingProtocol implements PairingProtocolInterface {
     const m6TLVBuffer = Buffer.from(m6DataBase64, 'base64');
     const m6Parsed = decodeTLV8ToDict(m6TLVBuffer);
 
-    PairingProtocol.log.debug(
+    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];
@@ -589,10 +622,7 @@ export class PairingProtocol implements PairingProtocolInterface {
         nonce,
       });
       const decryptedTLV = decodeTLV8ToDict(decrypted);
-      PairingProtocol.log.debug(
-        'M6 decrypted content types:',
-        Object.keys(decryptedTLV),
-      );
+      log.debug('M6 decrypted content types:', Object.keys(decryptedTLV));
     }
   }
 
@@ -610,7 +640,7 @@ export class PairingProtocol implements PairingProtocolInterface {
       length: 32,
     });
 
-    PairingProtocol.log.debug('Derived encryption keys');
+    log.debug('Derived encryption keys');
     return {
       encryptKey: sharedKey,
       decryptKey: sharedKey,

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

@@ -1,2 +1,2 @@
 export { PairingStorage } from './pairing-storage.js';
-export type { PairingStorageInterface } from './types.js';
+export type { PairingStorageInterface, PairRecord } from './types.js';

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

@@ -1,16 +1,20 @@
 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';
 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 class PairingStorage implements PairingStorageInterface {
-  private readonly log = logger.getLogger('PairingStorage');
+  private readonly log = getLogger('PairingStorage');
   private readonly box;
+  private strongboxDir?: string;
 
   constructor(private readonly config: PairingConfig) {
     this.box = strongbox(STRONGBOX_CONTAINER_NAME);
@@ -23,7 +27,7 @@ export class PairingStorage implements PairingStorageInterface {
     remoteUnlockHostKey = '',
   ): Promise<string> {
     try {
-      const itemName = `appletv_pairing_${deviceId}`;
+      const itemName = `${APPLETV_PAIRING_PREFIX}${deviceId}`;
       const plistContent = this.createPlistContent(
         ltpk,
         ltsk,
@@ -46,6 +50,70 @@ export class PairingStorage implements PairingStorageInterface {
     }
   }
 
+  async load(deviceId: string): Promise<PairRecord | null> {
+    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 as string, 'base64');
+      const publicKey = Buffer.isBuffer(parsed.public_key)
+        ? parsed.public_key
+        : Buffer.from(parsed.public_key as string, 'base64');
+
+      this.log.debug(`Loaded pair record for ${deviceId}`);
+
+      return {
+        privateKey,
+        publicKey,
+        remoteUnlockHostKey: (parsed.remote_unlock_host_key as string) || '',
+      };
+    } catch (error) {
+      this.log.error(`Failed to load pair record for ${deviceId}:`, error);
+      return null;
+    }
+  }
+
+  async getAvailableDeviceIds(): Promise<string[]> {
+    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: string) => file.startsWith(APPLETV_PAIRING_PREFIX))
+        .map((file: string) => 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 [];
+    }
+  }
+
   private createPlistContent(
     publicKey: Buffer,
     privateKey: Buffer,

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

@@ -1,4 +1,9 @@
-/** Interface for storing pairing credentials to disk */
+export interface PairRecord {
+  publicKey: Buffer;
+  privateKey: Buffer;
+  remoteUnlockHostKey: string;
+}
+
 export interface PairingStorageInterface {
   save(
     deviceId: string,
@@ -6,4 +11,6 @@ export interface PairingStorageInterface {
     ltsk: Buffer,
     remoteUnlockHostKey?: string,
   ): Promise<string>;
+  load(deviceId: string): Promise<PairRecord | null>;
+  getAvailableDeviceIds(): Promise<string[]>;
 }

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

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