appium-ios-remotexpc 0.0.4 → 0.0.6

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

@@ -0,0 +1,126 @@
+import { logger } from '@appium/support';
+import {
+  type KeyPairKeyObjectResult,
+  generateKeyPairSync,
+  sign,
+} from 'node:crypto';
+
+import { CryptographyError } from '../errors.js';
+import type { PairingKeys } from '../types.js';
+
+const log = logger.getLogger('Ed25519');
+
+const ED25519_PUBLIC_KEY_LENGTH = 32;
+const ED25519_PRIVATE_KEY_LENGTH = 32;
+const ED25519_PKCS8_PREFIX = Buffer.from(
+  '302e020100300506032b657004220420',
+  'hex',
+);
+
+/**
+ * Generates a new Ed25519 key pair for cryptographic operations
+ * @returns PairingKeys object containing 32-byte public and private key buffers
+ * @throws CryptographyError if key generation fails
+ */
+export function generateEd25519KeyPair(): PairingKeys {
+  try {
+    const keyPair: KeyPairKeyObjectResult = generateKeyPairSync('ed25519');
+
+    const publicKeyDer = keyPair.publicKey.export({
+      type: 'spki',
+      format: 'der',
+    }) as Buffer;
+
+    const privateKeyDer = keyPair.privateKey.export({
+      type: 'pkcs8',
+      format: 'der',
+    }) as Buffer;
+
+    const publicKeyBuffer = extractEd25519PublicKey(publicKeyDer);
+    const privateKeyBuffer = extractEd25519PrivateKey(privateKeyDer);
+
+    return {
+      publicKey: publicKeyBuffer,
+      privateKey: privateKeyBuffer,
+    };
+  } catch (error) {
+    log.error('Failed to generate Ed25519 key pair:', error);
+    const message = error instanceof Error ? error.message : String(error);
+    throw new CryptographyError(
+      `Failed to generate Ed25519 key pair: ${message}`,
+    );
+  }
+}
+
+/**
+ * Creates an Ed25519 digital signature for the provided data
+ * @param data - The data to sign
+ * @param privateKey - 32-byte Ed25519 private key
+ * @returns Buffer containing the 64-byte signature
+ * @throws CryptographyError if signing fails or private key is invalid
+ */
+export function createEd25519Signature(
+  data: Buffer,
+  privateKey: Buffer,
+): Buffer {
+  if (!data || data.length === 0) {
+    throw new CryptographyError('Data to sign cannot be empty');
+  }
+
+  if (!privateKey || privateKey.length !== ED25519_PRIVATE_KEY_LENGTH) {
+    throw new CryptographyError(
+      `Private key must be ${ED25519_PRIVATE_KEY_LENGTH} bytes`,
+    );
+  }
+
+  try {
+    const privateKeyDer = Buffer.concat([ED25519_PKCS8_PREFIX, privateKey]);
+
+    return sign(null, data, {
+      key: privateKeyDer,
+      format: 'der',
+      type: 'pkcs8',
+    });
+  } catch (error) {
+    log.error('Failed to create Ed25519 signature:', error);
+    const message = error instanceof Error ? error.message : String(error);
+    throw new CryptographyError(
+      `Failed to create Ed25519 signature: ${message}`,
+    );
+  }
+}
+
+/**
+ * Extracts the raw 32-byte public key from DER-encoded SPKI format
+ * @param publicKeyDer - DER-encoded public key
+ * @returns 32-byte public key buffer
+ * @throws CryptographyError if extraction fails
+ */
+function extractEd25519PublicKey(publicKeyDer: Buffer): Buffer {
+  if (publicKeyDer.length < ED25519_PUBLIC_KEY_LENGTH) {
+    throw new CryptographyError('Invalid public key DER format');
+  }
+
+  return publicKeyDer.subarray(publicKeyDer.length - ED25519_PUBLIC_KEY_LENGTH);
+}
+
+/**
+ * Extracts the raw 32-byte private key from DER-encoded PKCS#8 format
+ * @param privateKeyDer - DER-encoded private key
+ * @returns 32-byte private key buffer
+ * @throws CryptographyError if extraction fails
+ */
+function extractEd25519PrivateKey(privateKeyDer: Buffer): Buffer {
+  const octetStringPattern = Buffer.from([0x04, 0x20]);
+  const index = privateKeyDer.indexOf(octetStringPattern);
+
+  if (index !== -1 && index + 34 <= privateKeyDer.length) {
+    return privateKeyDer.subarray(index + 2, index + 34);
+  }
+
+  if (privateKeyDer.length >= 48) {
+    return privateKeyDer.subarray(16, 48);
+  }
+
+  throw new CryptographyError('Unable to extract private key from DER format');
+}

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

@@ -0,0 +1,95 @@
+import { logger } from '@appium/support';
+import { createHmac } from 'node:crypto';
+
+import { HKDF_HASH_ALGORITHM, HKDF_HASH_LENGTH } from '../constants.js';
+import { CryptographyError } from '../errors.js';
+
+const log = logger.getLogger('HKDF');
+
+export interface HKDFParams {
+  ikm: Buffer;
+  salt: Buffer | null;
+  info: Buffer;
+  length: number;
+}
+
+const MAX_OUTPUT_LENGTH = 255 * HKDF_HASH_LENGTH;
+
+/**
+ * HMAC-based Key Derivation Function (HKDF) as defined in RFC 5869
+ * Derives cryptographic keys from input key material using a two-step process:
+ * 1. Extract: Generate a pseudorandom key from the input key material
+ * 2. Expand: Expand the pseudorandom key to the desired output length
+ *
+ * @param params - HKDF parameters including input key material, salt, info, and desired output length
+ * @returns Buffer containing the derived key material of specified length
+ * @throws CryptographyError if derivation fails or parameters are invalid
+ */
+export function hkdf(params: HKDFParams): Buffer {
+  const { ikm, salt, info, length } = params;
+
+  if (!ikm || ikm.length === 0) {
+    throw new CryptographyError('Input key material (IKM) cannot be empty');
+  }
+
+  if (!info) {
+    throw new CryptographyError('Info parameter is required');
+  }
+
+  if (length <= 0) {
+    throw new CryptographyError('Output length must be positive');
+  }
+
+  if (length > MAX_OUTPUT_LENGTH) {
+    throw new CryptographyError(
+      `Output length cannot exceed ${MAX_OUTPUT_LENGTH} bytes`,
+    );
+  }
+
+  try {
+    const extractedKey = hkdfExtract(ikm, salt);
+    return hkdfExpand(extractedKey, info, length);
+  } catch (error) {
+    log.error('HKDF derivation failed:', error);
+    const message = error instanceof Error ? error.message : String(error);
+    throw new CryptographyError(`HKDF derivation failed: ${message}`);
+  }
+}
+
+/**
+ * HKDF Extract step: generates a pseudorandom key from input key material
+ * @param ikm - Input key material
+ * @param salt - Optional salt value (uses zero salt if null)
+ * @returns Pseudorandom key of hash length
+ */
+function hkdfExtract(ikm: Buffer, salt: Buffer | null): Buffer {
+  const actualSalt = salt || Buffer.alloc(HKDF_HASH_LENGTH);
+  return createHmac(HKDF_HASH_ALGORITHM, actualSalt).update(ikm).digest();
+}
+
+/**
+ * HKDF Expand a step: expands a pseudorandom key to desired output length
+ * @param prk - Pseudorandom key from extract step
+ * @param info - Context and application specific information
+ * @param length - Desired output key material length
+ * @returns Output key material of specified length
+ */
+function hkdfExpand(prk: Buffer, info: Buffer, length: number): Buffer {
+  const numberOfBlocks = Math.ceil(length / HKDF_HASH_LENGTH);
+  const blocks: Buffer[] = [];
+  let previousBlock: Buffer = Buffer.alloc(0);
+
+  for (let blockIndex = 1; blockIndex <= numberOfBlocks; blockIndex++) {
+    const hmac = createHmac(HKDF_HASH_ALGORITHM, prk);
+    hmac.update(previousBlock);
+    hmac.update(info);
+    hmac.update(Buffer.from([blockIndex]));
+
+    const currentBlock = hmac.digest();
+    blocks.push(currentBlock);
+    previousBlock = currentBlock;
+  }
+
+  const outputKeyMaterial = Buffer.concat(blocks);
+  return outputKeyMaterial.subarray(0, length);
+}

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

@@ -0,0 +1,11 @@
+export { Opack2 } from './opack2.js';
+
+export {
+  encryptChaCha20Poly1305,
+  decryptChaCha20Poly1305,
+  type ChaCha20Poly1305Params,
+} from './chacha20-poly1305.js';
+
+export { generateEd25519KeyPair, createEd25519Signature } from './ed25519.js';
+
+export { hkdf, type HKDFParams } from './hkdf.js';

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

@@ -0,0 +1,257 @@
+import * as constants from '../constants.js';
+import { AppleTVError } from '../errors.js';
+
+interface SerializableArray extends Array<SerializableValue> {}
+interface SerializableObject extends Record<string, SerializableValue> {}
+
+type SerializableValue =
+  | null
+  | undefined
+  | boolean
+  | number
+  | string
+  | Buffer
+  | SerializableArray
+  | SerializableObject;
+
+/**
+ * OPACK2 binary serialization format encoder
+ * Implements Apple's OPACK2 protocol for efficient binary serialization of structured data
+ */
+export class Opack2 {
+  /**
+   * Serializes a JavaScript object to OPACK2 binary format
+   * @param obj - The object to serialize (supports primitives, arrays, objects, and Buffers)
+   * @returns Buffer containing the serialized data
+   * @throws AppleTVError if the object contains unsupported types
+   */
+  static dumps(obj: SerializableValue): Buffer {
+    return this.encode(obj);
+  }
+
+  /**
+   * Main encoding dispatcher that routes values to appropriate type-specific encoders
+   * @param obj - Value to encode
+   * @returns Buffer containing encoded value
+   * @throws AppleTVError for unsupported types
+   */
+  private static encode(obj: SerializableValue): Buffer {
+    if (obj === null || obj === undefined) {
+      return Buffer.from([constants.OPACK2_NULL]);
+    }
+
+    if (typeof obj === 'boolean') {
+      return Buffer.from([
+        obj ? constants.OPACK2_TRUE : constants.OPACK2_FALSE,
+      ]);
+    }
+
+    if (typeof obj === 'number') {
+      return this.encodeNumber(obj);
+    }
+
+    if (typeof obj === 'string') {
+      return this.encodeString(obj);
+    }
+
+    if (Buffer.isBuffer(obj)) {
+      return this.encodeBytes(obj);
+    }
+
+    if (Array.isArray(obj)) {
+      return this.encodeArray(obj);
+    }
+
+    if (
+      typeof obj === 'object' &&
+      !Array.isArray(obj) &&
+      !Buffer.isBuffer(obj)
+    ) {
+      return this.encodeDict(obj as Record<string, SerializableValue>);
+    }
+
+    throw new AppleTVError(
+      `Unsupported type for OPACK2 serialization: ${typeof obj}`,
+    );
+  }
+
+  /**
+   * Encodes numeric values with the appropriate size optimization
+   * @param num - Number to encode
+   * @returns Buffer containing encoded number
+   */
+  private static encodeNumber(num: number): Buffer {
+    if (!Number.isInteger(num) || num < 0) {
+      const buffer = Buffer.allocUnsafe(5);
+      buffer[0] = constants.OPACK2_FLOAT_MARKER;
+      buffer.writeFloatLE(num, 1);
+      return buffer;
+    }
+
+    if (num <= constants.OPACK2_SMALL_INT_MAX) {
+      return Buffer.from([num + constants.OPACK2_SMALL_INT_OFFSET]);
+    }
+
+    if (num <= constants.OPACK2_UINT8_MAX) {
+      return Buffer.from([constants.OPACK2_INT8_MARKER, num]);
+    }
+
+    if (num <= constants.OPACK2_UINT32_MAX) {
+      const buffer = Buffer.allocUnsafe(5);
+      buffer[0] = constants.OPACK2_INT32_MARKER;
+      buffer.writeUInt32LE(num, 1);
+      return buffer;
+    }
+
+    if (num <= Number.MAX_SAFE_INTEGER) {
+      const buffer = Buffer.allocUnsafe(9);
+      buffer[0] = constants.OPACK2_INT64_MARKER;
+      buffer.writeBigUInt64LE(BigInt(num), 1);
+      return buffer;
+    }
+
+    throw new AppleTVError(`Number too large for OPACK2 encoding: ${num}`);
+  }
+
+  /**
+   * Encodes UTF-8 strings with length-optimized headers
+   * @param str - String to encode
+   * @returns Buffer containing encoded string
+   */
+  private static encodeString(str: string): Buffer {
+    const encoded = Buffer.from(str, 'utf8');
+    const length = encoded.length;
+
+    if (length <= constants.OPACK2_SMALL_STRING_MAX) {
+      return Buffer.concat([
+        Buffer.from([constants.OPACK2_SMALL_STRING_BASE + length]),
+        encoded,
+      ]);
+    }
+
+    if (length <= constants.OPACK2_UINT8_MAX) {
+      return Buffer.concat([
+        Buffer.from([constants.OPACK2_STRING_8BIT_LEN_MARKER, length]),
+        encoded,
+      ]);
+    }
+
+    if (length <= constants.OPACK2_UINT16_MAX) {
+      const header = Buffer.allocUnsafe(3);
+      header[0] = constants.OPACK2_STRING_16BIT_LEN_MARKER;
+      header.writeUInt16BE(length, 1);
+      return Buffer.concat([header, encoded]);
+    }
+
+    if (length <= constants.OPACK2_UINT32_MAX) {
+      const header = Buffer.allocUnsafe(5);
+      header[0] = constants.OPACK2_STRING_32BIT_LEN_MARKER;
+      header.writeUInt32BE(length, 1);
+      return Buffer.concat([header, encoded]);
+    }
+
+    throw new AppleTVError(
+      `String too long for OPACK2 encoding: ${length} bytes`,
+    );
+  }
+
+  /**
+   * Encodes binary data with length-optimized headers
+   * @param bytes - Buffer to encode
+   * @returns Buffer containing encoded binary data
+   */
+  private static encodeBytes(bytes: Buffer): Buffer {
+    const length = bytes.length;
+
+    if (length <= constants.OPACK2_SMALL_BYTES_MAX) {
+      return Buffer.concat([
+        Buffer.from([constants.OPACK2_SMALL_BYTES_BASE + length]),
+        bytes,
+      ]);
+    }
+
+    if (length <= constants.OPACK2_UINT8_MAX) {
+      return Buffer.concat([
+        Buffer.from([constants.OPACK2_BYTES_8BIT_LEN_MARKER, length]),
+        bytes,
+      ]);
+    }
+
+    if (length <= constants.OPACK2_UINT16_MAX) {
+      const header = Buffer.allocUnsafe(3);
+      header[0] = constants.OPACK2_BYTES_16BIT_LEN_MARKER;
+      header.writeUInt16BE(length, 1);
+      return Buffer.concat([header, bytes]);
+    }
+
+    if (length <= constants.OPACK2_UINT32_MAX) {
+      const header = Buffer.allocUnsafe(5);
+      header[0] = constants.OPACK2_BYTES_32BIT_LEN_MARKER;
+      header.writeUInt32BE(length, 1);
+      return Buffer.concat([header, bytes]);
+    }
+
+    throw new AppleTVError(
+      `Byte array too long for OPACK2 encoding: ${length} bytes`,
+    );
+  }
+
+  /**
+   * Encodes arrays with count-optimized headers
+   * @param arr - Array to encode
+   * @returns Buffer containing encoded array
+   */
+  private static encodeArray(arr: SerializableValue[]): Buffer {
+    const length = arr.length;
+
+    if (length <= constants.OPACK2_SMALL_ARRAY_MAX) {
+      const parts: Buffer[] = [
+        Buffer.from([constants.OPACK2_SMALL_ARRAY_BASE + length]),
+      ];
+      for (const item of arr) {
+        parts.push(this.encode(item));
+      }
+      return Buffer.concat(parts);
+    }
+
+    const parts: Buffer[] = [
+      Buffer.from([constants.OPACK2_VARIABLE_ARRAY_MARKER]),
+    ];
+    for (const item of arr) {
+      parts.push(this.encode(item));
+    }
+    parts.push(Buffer.from([constants.OPACK2_NULL]));
+    return Buffer.concat(parts);
+  }
+
+  /**
+   * Encodes objects/dictionaries with count-optimized headers
+   * @param dict - Object to encode
+   * @returns Buffer containing encoded dictionary
+   */
+  private static encodeDict(dict: Record<string, SerializableValue>): Buffer {
+    const entries = Object.entries(dict);
+    const length = entries.length;
+
+    if (length < constants.OPACK2_SMALL_DICT_MAX) {
+      const parts: Buffer[] = [
+        Buffer.from([constants.OPACK2_SMALL_DICT_BASE + length]),
+      ];
+      for (const [key, value] of entries) {
+        parts.push(this.encode(key));
+        parts.push(this.encode(value));
+      }
+      return Buffer.concat(parts);
+    }
+
+    const parts: Buffer[] = [
+      Buffer.from([constants.OPACK2_VARIABLE_DICT_MARKER]),
+    ];
+    for (const [key, value] of entries) {
+      parts.push(this.encode(key));
+      parts.push(this.encode(value));
+    }
+    parts.push(Buffer.from([constants.OPACK2_NULL, constants.OPACK2_NULL]));
+    return Buffer.concat(parts);
+  }
+}

package/src/lib/remote-xpc/remote-xpc-connection.ts

@@ -457,5 +457,4 @@ function extractServices(response: string): ServicesResponse {
   return { services };
 }
 
-export default RemoteXpcConnection;
-export { type Service, type ServicesResponse };
+export { RemoteXpcConnection, type Service, type ServicesResponse };

package/src/lib/tunnel/index.ts

@@ -2,7 +2,7 @@ import { logger } from '@appium/support';
 import type { TLSSocket } from 'tls';
 import { type TunnelConnection, connectToTunnelLockdown } from 'tuntap-bridge';
 
-import RemoteXpcConnection from '../remote-xpc/remote-xpc-connection.js';
+import { RemoteXpcConnection } from '../remote-xpc/remote-xpc-connection.js';
 
 const log = logger.getLogger('TunnelManager');
 
@@ -64,9 +64,12 @@ class TunnelManagerService {
   async createRemoteXPCConnection(
     address: string,
     rsdPort: number,
-  ): Promise<any> {
+  ): Promise<RemoteXpcConnection> {
     try {
-      const remoteXPC = new RemoteXpcConnection([address, rsdPort]);
+      const remoteXPC: RemoteXpcConnection = new RemoteXpcConnection([
+        address,
+        rsdPort,
+      ]);
 
       // Connect to RemoteXPC with delay between retries
       let retries = 3;
@@ -75,7 +78,6 @@ class TunnelManagerService {
       while (retries > 0) {
         try {
           await remoteXPC.connect();
-
           // Update the registry entry with the RemoteXPC connection
           const entry = this.tunnelRegistry.get(address);
           if (entry) {
@@ -249,5 +251,5 @@ class TunnelManagerService {
 // Create and export the singleton instance
 export const TunnelManager = new TunnelManagerService();
 // Export packet streaming IPC functionality
-export { PacketStreamServer } from './packet-stream-server.js';
 export { PacketStreamClient } from './packet-stream-client.js';
+export { PacketStreamServer } from './packet-stream-server.js';

package/src/lib/types.ts

@@ -5,6 +5,7 @@ import { EventEmitter } from 'events';
 import type { PacketData } from 'tuntap-bridge';
 
 import type { BaseService, Service } from '../services/ios/base-service.js';
+import type { RemoteXpcConnection } from './remote-xpc/remote-xpc-connection.js';
 import type { Device } from './usbmux/index.js';
 
 /**
@@ -190,6 +191,17 @@ export interface DiagnosticsServiceConstructor {
   new (address: [string, number]): DiagnosticsService;
 }
 
+/**
+ * Represents a DiagnosticsService instance with its associated RemoteXPC connection
+ * This allows callers to properly manage the connection lifecycle
+ */
+export interface DiagnosticsServiceWithConnection {
+  /** The DiagnosticsService instance */
+  diagnosticsService: DiagnosticsService;
+  /** The RemoteXPC connection that can be used to close the connection */
+  remoteXPC: RemoteXpcConnection;
+}
+
 /**
  * Options for configuring syslog capture
  */

package/src/services/ios/diagnostic-service/index.ts

@@ -223,7 +223,6 @@ class DiagnosticsService
       emptyRequest,
       timeout,
     );
-    log.debug('Additional response: ', additionalResponse);
     const hasDiagnostics =
       'Diagnostics' in additionalResponse &&
       typeof additionalResponse.Diagnostics === 'object' &&

package/src/services.ts

@@ -1,10 +1,10 @@
 import { strongbox } from '@appium/strongbox';
 
-import RemoteXpcConnection from './lib/remote-xpc/remote-xpc-connection.js';
+import { RemoteXpcConnection } from './lib/remote-xpc/remote-xpc-connection.js';
 import { TunnelManager } from './lib/tunnel/index.js';
 import { TunnelApiClient } from './lib/tunnel/tunnel-api-client.js';
 import type {
-  DiagnosticsService as DiagnosticsServiceType,
+  DiagnosticsServiceWithConnection,
   SyslogService as SyslogServiceType,
 } from './lib/types.js';
 import DiagnosticsService from './services/ios/diagnostic-service/index.js';
@@ -15,15 +15,18 @@ const TUNNEL_REGISTRY_PORT = 'tunnelRegistryPort';
 
 export async function startDiagnosticsService(
   udid: string,
-): Promise<DiagnosticsServiceType> {
+): Promise<DiagnosticsServiceWithConnection> {
   const { remoteXPC, tunnelConnection } = await createRemoteXPCConnection(udid);
   const diagnosticsService = remoteXPC.findService(
     DiagnosticsService.RSD_SERVICE_NAME,
   );
-  return new DiagnosticsService([
-    tunnelConnection.host,
-    parseInt(diagnosticsService.port, 10),
-  ]);
+  return {
+    remoteXPC: remoteXPC as RemoteXpcConnection,
+    diagnosticsService: new DiagnosticsService([
+      tunnelConnection.host,
+      parseInt(diagnosticsService.port, 10),
+    ]),
+  };
 }
 
 export async function startSyslogService(