appium-ios-remotexpc 0.16.1 → 0.18.0

package/src/services/ios/dvt/index.ts

@@ -509,11 +509,15 @@ export class DVTSecureSocketProxyService extends BaseService {
    * Archive a value using NSKeyedArchiver format for DTX protocol
    */
   private archiveValue(value: any): Buffer {
+    // Handle null values by referencing the $null marker
+    const rootIndex = value === null ? 0 : 1;
+    const objects = value === null ? ['$null'] : ['$null', value];
+
     const archived = {
       $version: 100000,
       $archiver: 'NSKeyedArchiver',
-      $top: { root: new PlistUID(1) },
-      $objects: ['$null', value],
+      $top: { root: new PlistUID(rootIndex) },
+      $objects: objects,
     };
 
     return createBinaryPlist(archived);

package/src/services/ios/dvt/instruments/application-listing.ts

@@ -0,0 +1,97 @@
+import { getLogger } from '../../../../lib/logger.js';
+import type { Channel } from '../channel.js';
+import { MessageAux } from '../dtx-message.js';
+import type { DVTSecureSocketProxyService } from '../index.js';
+
+const log = getLogger('ApplicationListing');
+
+export interface iOSApplication {
+  /** Display name of the application/plugin */
+  DisplayName: string;
+
+  /** Bundle identifier in reverse domain notation */
+  CFBundleIdentifier: string;
+
+  /** Full path to the application bundle */
+  BundlePath: string;
+
+  /** Version string of the application */
+  Version: string;
+
+  /** Name of the main executable file */
+  ExecutableName: string;
+
+  /** Access restriction flag (0 = unrestricted, 1 = restricted) */
+  Restricted: number;
+
+  /** Bundle type (e.g., 'PluginKit', 'Application') */
+  Type: string;
+
+  /** Unique identifier for plugins */
+  PluginIdentifier: string;
+
+  /** UUID for the plugin instance */
+  PluginUUID: string;
+
+  /** Extension configuration with variable structure */
+  ExtensionDictionary?: Record<string, any>;
+
+  /** Bundle identifier of the containing app (plugins only) */
+  ContainerBundleIdentifier?: string;
+
+  /** Path to the container app bundle (plugins only) */
+  ContainerBundlePath?: string;
+}
+
+/**
+ * Application Listing service for retrieving installed applications
+ */
+export class ApplicationListing {
+  static readonly IDENTIFIER =
+    'com.apple.instruments.server.services.device.applictionListing';
+
+  private channel: Channel | null = null;
+
+  constructor(private readonly dvt: DVTSecureSocketProxyService) {}
+
+  /**
+   * Initialize the application listing channel
+   */
+  async initialize(): Promise<void> {
+    if (this.channel) {
+      return;
+    }
+    this.channel = await this.dvt.makeChannel(ApplicationListing.IDENTIFIER);
+  }
+
+  /**
+   * Get the list of installed applications from the device
+   * @returns {Promise<iOSApplication[]>}
+   */
+  async list(): Promise<iOSApplication[]> {
+    await this.initialize();
+
+    const args = new MessageAux().appendObj(null).appendObj(null);
+
+    await this.channel!.call(
+      'installedApplicationsMatching_registerUpdateToken_',
+    )(args);
+
+    const result = await this.channel!.receivePlist();
+
+    if (!result) {
+      log.warn(
+        'Received null/undefined response from installedApplicationsMatching',
+      );
+      return [];
+    }
+
+    if (Array.isArray(result)) {
+      return result;
+    }
+
+    throw new Error(
+      `Unexpected response format from installedApplicationsMatching: ${JSON.stringify(result)}`,
+    );
+  }
+}

package/src/services/ios/dvt/instruments/device-info.ts

@@ -0,0 +1,217 @@
+import { getLogger } from '../../../../lib/logger.js';
+import { parseBinaryPlist } from '../../../../lib/plist/index.js';
+import type { ProcessInfo } from '../../../../lib/types.js';
+import type { Channel } from '../channel.js';
+import { MessageAux } from '../dtx-message.js';
+import type { DVTSecureSocketProxyService } from '../index.js';
+
+const log = getLogger('DeviceInfo');
+
+/**
+ * DeviceInfo service provides access to device information, file system,
+ * and process management through the DTX protocol.
+ *
+ * Available methods:
+ * - ls(path): List directory contents
+ * - execnameForPid(pid): Get executable path for a process ID
+ * - proclist(): Get list of running processes
+ * - isRunningPid(pid): Check if a process is running
+ * - hardwareInformation(): Get hardware details
+ * - networkInformation(): Get network configuration
+ * - machTimeInfo(): Get mach time information
+ * - machKernelName(): Get kernel name
+ * - kpepDatabase(): Get kernel performance event database
+ * - traceCodes(): Get trace code mappings
+ * - nameForUid(uid): Get username for UID
+ * - nameForGid(gid): Get group name for GID
+ */
+export class DeviceInfo {
+  static readonly IDENTIFIER =
+    'com.apple.instruments.server.services.deviceinfo';
+
+  private channel: Channel | null = null;
+  constructor(private readonly dvt: DVTSecureSocketProxyService) {}
+
+  /**
+   * Initialize the device info channel
+   */
+  async initialize(): Promise<void> {
+    if (!this.channel) {
+      this.channel = await this.dvt.makeChannel(DeviceInfo.IDENTIFIER);
+    }
+  }
+
+  /**
+   * List directory contents at the specified path.
+   * @param path - The directory path to list
+   * @returns Array of filenames
+   * @throws {Error} If the directory doesn't exist or cannot be accessed
+   */
+  async ls(path: string): Promise<string[]> {
+    const result = await this.requestInformation(
+      'directoryListingForPath_',
+      path,
+    );
+
+    if (result === null || result === undefined) {
+      throw new Error(`Failed to list directory: ${path}`);
+    }
+
+    log.debug(`Listed directory ${path}: ${result.length} entries`);
+    return result;
+  }
+
+  /**
+   * Get the full executable path for a given process ID.
+   * @param pid - The process identifier
+   * @returns The full path to the executable
+   */
+  async execnameForPid(pid: number): Promise<string> {
+    return this.requestInformation('execnameForPid_', pid);
+  }
+
+  /**
+   * Get the list of all running processes on the device.
+   * @returns Array of process information objects
+   */
+  async proclist(): Promise<ProcessInfo[]> {
+    const result = await this.requestInformation('runningProcesses');
+
+    if (!Array.isArray(result)) {
+      throw new Error(
+        `proclist returned invalid data: expected an array, got ${typeof result} (${JSON.stringify(result)})`,
+      );
+    }
+
+    log.debug(`Retrieved ${result.length} running processes`);
+    return result;
+  }
+
+  /**
+   * Check if a process with the given PID is currently running.
+   * @param pid - The process identifier to check
+   * @returns true if the process is running, false otherwise
+   */
+  async isRunningPid(pid: number): Promise<boolean> {
+    return this.requestInformation('isRunningPid_', pid);
+  }
+
+  /**
+   * Get hardware information about the device.
+   * @returns Object containing hardware information
+   */
+  async hardwareInformation(): Promise<any> {
+    return this.requestInformation('hardwareInformation');
+  }
+
+  /**
+   * Get network configuration information.
+   * @returns Object containing network information
+   */
+  async networkInformation(): Promise<any> {
+    return this.requestInformation('networkInformation');
+  }
+
+  /**
+   * Get mach kernel time information.
+   * @returns Object containing mach time info
+   */
+  async machTimeInfo(): Promise<any> {
+    return this.requestInformation('machTimeInfo');
+  }
+
+  /**
+   * Get the mach kernel name.
+   * @returns The kernel name string
+   */
+  async machKernelName(): Promise<string> {
+    return this.requestInformation('machKernelName');
+  }
+
+  /**
+   * Get the kernel performance event (kpep) database.
+   * @returns Object containing kpep database or null if not available
+   */
+  async kpepDatabase(): Promise<any | null> {
+    const kpepData = await this.requestInformation('kpepDatabase');
+
+    if (kpepData === null || kpepData === undefined) {
+      return null;
+    }
+
+    // The kpepDatabase is returned as binary plist data
+    if (Buffer.isBuffer(kpepData)) {
+      try {
+        return parseBinaryPlist(kpepData);
+      } catch (error) {
+        log.warn('Failed to parse kpep database:', error);
+        return null;
+      }
+    }
+
+    return kpepData;
+  }
+
+  /**
+   * Get trace code mappings.
+   * @returns Object mapping trace codes (as hex strings) to descriptions
+   */
+  async traceCodes(): Promise<Record<string, string>> {
+    const codesFile = await this.requestInformation('traceCodesFile');
+    if (typeof codesFile !== 'string') {
+      return {};
+    }
+
+    const codes: Record<string, string> = {};
+
+    for (const line of codesFile.split('\n')) {
+      const match = line.trim().match(/^(\S+)\s+(.+)$/);
+      if (match) {
+        const [, hex, description] = match;
+        codes[hex] = description;
+      }
+    }
+
+    log.debug(`Retrieved ${Object.keys(codes).length} trace codes`);
+    return codes;
+  }
+
+  /**
+   * Get the username for a given user ID (UID).
+   * @param uid - The user identifier
+   * @returns The username string
+   */
+  async nameForUid(uid: number): Promise<string> {
+    return this.requestInformation('nameForUID_', uid);
+  }
+
+  /**
+   * Get the group name for a given group ID (GID).
+   * @param gid - The group identifier
+   * @returns The group name string
+   */
+  async nameForGid(gid: number): Promise<string> {
+    return this.requestInformation('nameForGID_', gid);
+  }
+
+  /**
+   * Generic method to request information from the device.
+   * @param selectorName - The selector name to call
+   * @param arg - Optional argument to pass to the selector
+   * @returns The information object or value returned by the selector
+   * @private
+   */
+  private async requestInformation(
+    selectorName: string,
+    arg?: any,
+  ): Promise<any> {
+    await this.initialize();
+
+    const call = this.channel!.call(selectorName);
+    const args =
+      arg !== undefined ? new MessageAux().appendObj(arg) : undefined;
+
+    await call(args);
+    return this.channel!.receivePlist();
+  }
+}

package/src/services/ios/dvt/nskeyedarchiver-decoder.ts

@@ -1,6 +1,7 @@
 import { getLogger } from '../../../lib/logger.js';
 
 const log = getLogger('NSKeyedArchiverDecoder');
+const MAX_DECODE_DEPTH = 1000;
 
 /**
  * Decode NSKeyedArchiver formatted data into native JavaScript objects
@@ -79,50 +80,77 @@ export class NSKeyedArchiverDecoder {
   /**
    * Decode an object at a specific index
    */
-  private decodeObject(index: number): any {
+  private decodeObject(
+    index: number,
+    visited: Set<number> = new Set(),
+    depth: number = 0,
+  ): any {
+    // Prevent stack overflow with depth limit
+    if (depth > MAX_DECODE_DEPTH) {
+      log.warn(`Maximum decode depth exceeded at index ${index}`);
+      return null;
+    }
     if (index < 0 || index >= this.objects.length) {
       return null;
     }
 
+    // Prevent infinite recursion
+    if (visited.has(index)) {
+      return null; // Return null for circular references
+    }
+
     // Check cache
     if (this.decoded.has(index)) {
       return this.decoded.get(index);
     }
 
+    visited.add(index);
     const obj = this.objects[index];
 
     // Handle null marker
     if (obj === '$null' || obj === null) {
+      visited.delete(index);
       return null;
     }
 
     // Handle primitive types
     if (typeof obj !== 'object') {
+      visited.delete(index);
       return obj;
     }
 
     // Handle Buffer/binary data (eg. screenshots)
     if (Buffer.isBuffer(obj)) {
       this.decoded.set(index, obj);
+      visited.delete(index);
       return obj;
     }
 
     // Handle UID references
     if ('CF$UID' in obj) {
-      return this.decodeObject(obj.CF$UID);
+      const result = this.decodeObject(obj.CF$UID, visited, depth + 1);
+      visited.delete(index);
+      return result;
     }
 
     // Handle NSDictionary (NS.keys + NS.objects) - check this FIRST before NSArray
     if ('NS.keys' in obj && 'NS.objects' in obj) {
-      const result = this.decodeDictionary(obj['NS.keys'], obj['NS.objects']);
+      const result = this.decodeDictionary(
+        obj['NS.keys'],
+        obj['NS.objects'],
+        visited,
+        depth,
+      );
       this.decoded.set(index, result);
+      visited.delete(index);
       return result;
     }
 
     // Handle NSArray (NS.objects only, without NS.keys)
     if ('NS.objects' in obj) {
-      const result = this.decodeArray(obj['NS.objects']);
+      const result = this.decodeArray(obj['NS.objects'], visited, depth);
       this.decoded.set(index, result);
+      visited.delete(index);
       return result;
     }
 
@@ -135,20 +163,25 @@ export class NSKeyedArchiverDecoder {
 
       if (typeof value === 'number') {
         // Could be a reference or primitive
-        const referenced = this.objects[value];
-        if (
-          referenced &&
-          typeof referenced === 'object' &&
-          referenced !== '$null'
-        ) {
-          result[key] = this.decodeObject(value);
+        if (value < this.objects.length && value >= 0) {
+          const referenced = this.objects[value];
+          if (
+            referenced &&
+            typeof referenced === 'object' &&
+            referenced !== '$null' &&
+            !visited.has(value)
+          ) {
+            result[key] = this.decodeObject(value, visited, depth + 1);
+          } else {
+            result[key] = value;
+          }
         } else {
           result[key] = value;
         }
       } else if (typeof value === 'object' && value && 'CF$UID' in value) {
         const uid = (value as any).CF$UID;
-        if (typeof uid === 'number') {
-          result[key] = this.decodeObject(uid);
+        if (typeof uid === 'number' && !visited.has(uid)) {
+          result[key] = this.decodeObject(uid, visited, depth + 1);
         } else {
           result[key] = value;
         }
@@ -158,22 +191,27 @@ export class NSKeyedArchiverDecoder {
     }
 
     this.decoded.set(index, result);
+    visited.delete(index);
     return result;
   }
 
   /**
    * Decode an NSArray
    */
-  private decodeArray(refs: any): any[] {
+  private decodeArray(
+    refs: any,
+    visited: Set<number> = new Set(),
+    depth: number = 0,
+  ): any[] {
     if (!Array.isArray(refs)) {
       return [];
     }
 
     return refs.map((ref) => {
       if (typeof ref === 'number') {
-        return this.decodeObject(ref);
+        return this.decodeObject(ref, visited, depth + 1);
       } else if (typeof ref === 'object' && ref && 'CF$UID' in ref) {
-        return this.decodeObject(ref.CF$UID);
+        return this.decodeObject(ref.CF$UID, visited, depth + 1);
       }
       return ref;
     });
@@ -182,7 +220,12 @@ export class NSKeyedArchiverDecoder {
   /**
    * Decode an NSDictionary
    */
-  private decodeDictionary(keyRefs: any, valueRefs: any): any {
+  private decodeDictionary(
+    keyRefs: any,
+    valueRefs: any,
+    visited: Set<number> = new Set(),
+    depth: number = 0,
+  ): any {
     if (!Array.isArray(keyRefs) || !Array.isArray(valueRefs)) {
       return {};
     }
@@ -190,8 +233,8 @@ export class NSKeyedArchiverDecoder {
     const result: any = {};
 
     for (let i = 0; i < keyRefs.length && i < valueRefs.length; i++) {
-      const key = this.decodeObject(keyRefs[i]);
-      const value = this.decodeObject(valueRefs[i]);
+      const key = this.decodeObject(keyRefs[i], visited, depth + 1);
+      const value = this.decodeObject(valueRefs[i], visited, depth + 1);
 
       if (typeof key === 'string') {
         result[key] = value;

package/src/services.ts

@@ -18,7 +18,9 @@ import type {
 import AfcService from './services/ios/afc/index.js';
 import DiagnosticsService from './services/ios/diagnostic-service/index.js';
 import { DVTSecureSocketProxyService } from './services/ios/dvt/index.js';
+import { ApplicationListing } from './services/ios/dvt/instruments/application-listing.js';
 import { ConditionInducer } from './services/ios/dvt/instruments/condition-inducer.js';
+import { DeviceInfo } from './services/ios/dvt/instruments/device-info.js';
 import { Graphics } from './services/ios/dvt/instruments/graphics.js';
 import { LocationSimulation } from './services/ios/dvt/instruments/location-simulation.js';
 import { Screenshot } from './services/ios/dvt/instruments/screenshot.js';
@@ -203,7 +205,9 @@ export async function startDVTService(
   const locationSimulation = new LocationSimulation(dvtService);
   const conditionInducer = new ConditionInducer(dvtService);
   const screenshot = new Screenshot(dvtService);
+  const appListing = new ApplicationListing(dvtService);
   const graphics = new Graphics(dvtService);
+  const deviceInfo = new DeviceInfo(dvtService);
 
   return {
     remoteXPC: remoteXPC as RemoteXpcConnection,
@@ -211,7 +215,9 @@ export async function startDVTService(
     locationSimulation,
     conditionInducer,
     screenshot,
+    appListing,
     graphics,
+    deviceInfo,
   };
 }