appium-ios-remotexpc 0.13.2 → 0.14.0

package/src/services/ios/dvt/instruments/condition-inducer.ts

@@ -0,0 +1,140 @@
+import { getLogger } from '../../../../lib/logger.js';
+import type { ConditionGroup } 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('ConditionInducer');
+
+/**
+ * Condition Inducer service for simulating various device conditions
+ * such as network conditions, thermal states, etc.
+ */
+export class ConditionInducer {
+  static readonly IDENTIFIER =
+    'com.apple.instruments.server.services.ConditionInducer';
+
+  private channel: Channel | null = null;
+
+  constructor(private readonly dvt: DVTSecureSocketProxyService) {}
+
+  /**
+   * Initialize the condition inducer channel
+   */
+  async initialize(): Promise<void> {
+    if (this.channel) {
+      return;
+    }
+    this.channel = await this.dvt.makeChannel(ConditionInducer.IDENTIFIER);
+  }
+
+  /**
+   * List all available condition inducers and their profiles
+   * @returns Array of condition groups with their available profiles
+   */
+  async list(): Promise<ConditionGroup[]> {
+    await this.initialize();
+
+    await this.channel!.call('availableConditionInducers')();
+    const result = await this.channel!.receivePlist();
+
+    // Handle different response formats
+    if (!result) {
+      log.warn(
+        'Received null/undefined response from availableConditionInducers',
+      );
+      return [];
+    }
+
+    // If result is already an array, return it
+    if (Array.isArray(result)) {
+      return result as ConditionGroup[];
+    }
+
+    throw new Error(
+      `Unexpected response format from availableConditionInducers: ${JSON.stringify(result)}`,
+    );
+  }
+
+  /**
+   * Set a specific condition profile
+   * @param profileIdentifier The identifier of the profile to enable
+   * @throws Error if the profile identifier is not found
+   * @throws Error if a condition is already active
+   */
+  async set(profileIdentifier: string): Promise<void> {
+    await this.initialize();
+
+    const groups = await this.list();
+
+    // Find the profile in the available groups
+    for (const group of groups) {
+      const profiles = group.profiles || [];
+      for (const profile of profiles) {
+        if (profileIdentifier !== profile.identifier) {
+          continue;
+        }
+
+        log.info(
+          `Enabling condition: ${profile.description || profile.identifier}`,
+        );
+
+        const args = new MessageAux()
+          .appendObj(group.identifier)
+          .appendObj(profile.identifier);
+
+        await this.channel!.call(
+          'enableConditionWithIdentifier_profileIdentifier_',
+        )(args);
+
+        // Wait for response which may be a raised NSError
+        await this.channel!.receivePlist();
+
+        log.info(
+          `Successfully enabled condition profile: ${profileIdentifier}`,
+        );
+        return;
+      }
+    }
+
+    const availableProfiles = groups.flatMap((group) =>
+      (group.profiles || []).map((p) => p.identifier),
+    );
+
+    throw new Error(
+      `Invalid profile identifier: ${profileIdentifier}. Available profiles: ${availableProfiles.join(', ')}`,
+    );
+  }
+
+  /**
+   * Disable the currently active condition
+   *
+   * Note: This method is idempotent - calling it when no condition is active
+   * will not throw an error.
+   */
+  async disable(): Promise<void> {
+    await this.initialize();
+
+    await this.channel!.call('disableActiveCondition')();
+    const response = await this.channel!.receivePlist();
+
+    // Response can be:
+    // - true (successfully disabled condition)
+    // - NSError object, when no condition is active
+    if (response === true) {
+      log.info('Disabled active condition');
+    } else if (this.isNSError(response)) {
+      log.debug('No active condition to disable');
+    } else {
+      throw new Error(
+        `Unexpected response from disableActiveCondition: ${JSON.stringify(response)}`,
+      );
+    }
+  }
+
+  private isNSError(obj: any): boolean {
+    return ['NSCode', 'NSUserInfo', 'NSDomain'].some(
+      (prop) => obj?.[prop] !== undefined,
+    );
+  }
+}

package/src/services/ios/dvt/instruments/location-simulation.ts

@@ -0,0 +1,83 @@
+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('LocationSimulation');
+
+/**
+ * Geographic coordinates
+ */
+export interface LocationCoordinates {
+  latitude: number;
+  longitude: number;
+}
+
+/**
+ * Location simulation service for simulating device GPS location
+ */
+export class LocationSimulation {
+  static readonly IDENTIFIER =
+    'com.apple.instruments.server.services.LocationSimulation';
+
+  private channel: Channel | null = null;
+
+  constructor(private readonly dvt: DVTSecureSocketProxyService) {}
+
+  /**
+   * Initialize the location simulation channel
+   */
+  async initialize(): Promise<void> {
+    if (this.channel) {
+      return;
+    }
+
+    this.channel = await this.dvt.makeChannel(LocationSimulation.IDENTIFIER);
+  }
+
+  /**
+   * Set the simulated GPS location
+   * @param coordinates The location coordinates
+   */
+  async set(coordinates: LocationCoordinates): Promise<void> {
+    await this.initialize();
+
+    const args = new MessageAux()
+      .appendObj(coordinates.latitude)
+      .appendObj(coordinates.longitude);
+
+    await this.channel!.call('simulateLocationWithLatitude_longitude_')(args);
+    await this.channel!.receivePlist();
+
+    log.info(
+      `Location set to: ${coordinates.latitude}, ${coordinates.longitude}`,
+    );
+  }
+
+  /**
+   * Set the simulated GPS location
+   * @param latitude The latitude coordinate
+   * @param longitude The longitude coordinate
+   */
+  async setLocation(latitude: number, longitude: number): Promise<void> {
+    await this.set({ latitude, longitude });
+  }
+
+  /**
+   * Stop location simulation and restore the actual device location
+   *
+   * Note: This method is safe to call even if no location simulation is currently active.
+   */
+  async clear(): Promise<void> {
+    await this.initialize();
+    await this.channel!.call('stopLocationSimulation')();
+    log.info('Location simulation stopped');
+  }
+
+  /**
+   * Stop location simulation (alias for clear)
+   */
+  async stop(): Promise<void> {
+    await this.clear();
+  }
+}

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

@@ -0,0 +1,219 @@
+import { getLogger } from '../../../lib/logger.js';
+
+const log = getLogger('NSKeyedArchiverDecoder');
+
+/**
+ * Decode NSKeyedArchiver formatted data into native JavaScript objects
+ *
+ * NSKeyedArchiver is Apple's serialization format that stores object graphs
+ * with references. The format includes:
+ * - $version: Archive version (typically 100000)
+ * - $archiver: "NSKeyedArchiver"
+ * - $top: Root object references
+ * - $objects: Array of all objects with cross-references
+ */
+export class NSKeyedArchiverDecoder {
+  private readonly objects: any[];
+  private readonly decoded: Map<number, any>;
+  private readonly archive: any;
+
+  constructor(data: any) {
+    if (!NSKeyedArchiverDecoder.isNSKeyedArchive(data)) {
+      throw new Error('Data is not in NSKeyedArchiver format');
+    }
+
+    this.archive = data;
+    this.objects = data.$objects || [];
+    this.decoded = new Map();
+  }
+
+  /**
+   * Check if data is in NSKeyedArchiver format
+   */
+  static isNSKeyedArchive(data: any): boolean {
+    if (!data || typeof data !== 'object') {
+      return false;
+    }
+
+    return (
+      '$archiver' in data &&
+      data.$archiver === 'NSKeyedArchiver' &&
+      '$objects' in data &&
+      Array.isArray(data.$objects)
+    );
+  }
+
+  /**
+   * Decode the entire archive starting from the root
+   */
+  decode(): any {
+    if (!this.objects || this.objects.length === 0) {
+      return null;
+    }
+
+    // Extract root reference from $top
+    let rootIndex: number | null = null;
+
+    if (this.archive.$top && typeof this.archive.$top === 'object') {
+      const top = this.archive.$top;
+      if ('root' in top) {
+        const root = top.root;
+        if (typeof root === 'number') {
+          rootIndex = root;
+        } else if (typeof root === 'object' && root && 'CF$UID' in root) {
+          rootIndex = (root as any).CF$UID;
+        }
+      }
+    }
+
+    // If we found the root index, decode it
+    if (rootIndex !== null) {
+      return this.decodeObject(rootIndex);
+    }
+
+    // Fallback: decode first non-null object
+    log.warn('Could not find root reference, using fallback');
+    return this.decodeObject(1);
+  }
+
+  /**
+   * Decode an object at a specific index
+   */
+  private decodeObject(index: number): any {
+    if (index < 0 || index >= this.objects.length) {
+      return null;
+    }
+
+    // Check cache
+    if (this.decoded.has(index)) {
+      return this.decoded.get(index);
+    }
+
+    const obj = this.objects[index];
+
+    // Handle null marker
+    if (obj === '$null' || obj === null) {
+      return null;
+    }
+
+    // Handle primitive types
+    if (typeof obj !== 'object') {
+      return obj;
+    }
+
+    // Handle UID references
+    if ('CF$UID' in obj) {
+      return this.decodeObject(obj.CF$UID);
+    }
+
+    // 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']);
+      this.decoded.set(index, result);
+      return result;
+    }
+
+    // Handle NSArray (NS.objects only, without NS.keys)
+    if ('NS.objects' in obj) {
+      const result = this.decodeArray(obj['NS.objects']);
+      this.decoded.set(index, result);
+      return result;
+    }
+
+    // Handle regular objects - just return as-is but resolve references
+    const result: any = {};
+    for (const [key, value] of Object.entries(obj)) {
+      if (key === '$class') {
+        continue; // Skip class metadata
+      }
+
+      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);
+        } 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);
+        } else {
+          result[key] = value;
+        }
+      } else {
+        result[key] = value;
+      }
+    }
+
+    this.decoded.set(index, result);
+    return result;
+  }
+
+  /**
+   * Decode an NSArray
+   */
+  private decodeArray(refs: any): any[] {
+    if (!Array.isArray(refs)) {
+      return [];
+    }
+
+    return refs.map((ref) => {
+      if (typeof ref === 'number') {
+        return this.decodeObject(ref);
+      } else if (typeof ref === 'object' && ref && 'CF$UID' in ref) {
+        return this.decodeObject(ref.CF$UID);
+      }
+      return ref;
+    });
+  }
+
+  /**
+   * Decode an NSDictionary
+   */
+  private decodeDictionary(keyRefs: any, valueRefs: any): any {
+    if (!Array.isArray(keyRefs) || !Array.isArray(valueRefs)) {
+      return {};
+    }
+
+    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]);
+
+      if (typeof key === 'string') {
+        result[key] = value;
+      }
+    }
+
+    return result;
+  }
+}
+
+/**
+ * Decode NSKeyedArchiver data or return as-is if not archived
+ */
+export function decodeNSKeyedArchiver(data: any): any {
+  if (!data) {
+    return data;
+  }
+
+  // Check if this is NSKeyedArchiver format
+  if (!NSKeyedArchiverDecoder.isNSKeyedArchive(data)) {
+    return data;
+  }
+
+  try {
+    const decoder = new NSKeyedArchiverDecoder(data);
+    return decoder.decode();
+  } catch (error) {
+    log.warn('Failed to decode NSKeyedArchiver data:', error);
+    return data;
+  }
+}

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

@@ -0,0 +1,89 @@
+import type { PlistDictionary } from '../../../lib/types.js';
+
+export function isPlainObject(value: any): value is Record<string, any> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+export function hasProperties(obj: any, ...props: string[]): boolean {
+  return isPlainObject(obj) ? props.every((prop) => prop in obj) : false;
+}
+
+export function isNSKeyedArchiverFormat(data: any): boolean {
+  return (
+    hasProperties(data, '$objects') &&
+    Array.isArray(data.$objects) &&
+    data.$objects.length > 0
+  );
+}
+
+export function isNSDictionaryFormat(obj: any): boolean {
+  return hasProperties(obj, 'NS.keys', 'NS.objects');
+}
+
+export function hasNSErrorIndicators(obj: any): boolean {
+  if (!isPlainObject(obj)) {
+    return false;
+  }
+
+  const errorProps = ['NSCode', 'NSUserInfo', 'NSDomain'];
+  return errorProps.some((prop) => prop in obj);
+}
+
+/**
+ * Extract $objects array from NSKeyedArchiver format, returns null if invalid
+ */
+export function extractNSKeyedArchiverObjects(data: any): any[] | null {
+  if (!isNSKeyedArchiverFormat(data)) {
+    return null;
+  }
+
+  const objects = data.$objects;
+  return objects.length > 1 ? objects : null;
+}
+
+/**
+ * Extract NSDictionary from NSKeyedArchiver objects using key/value references
+ */
+export function extractNSDictionary(
+  dictObj: any,
+  objects: any[],
+): PlistDictionary {
+  if (!isNSDictionaryFormat(dictObj)) {
+    return {};
+  }
+
+  const keysRef = dictObj['NS.keys'];
+  const valuesRef = dictObj['NS.objects'];
+
+  if (!Array.isArray(keysRef) || !Array.isArray(valuesRef)) {
+    return {};
+  }
+
+  const result: PlistDictionary = {};
+  for (let i = 0; i < keysRef.length; i++) {
+    const key = objects[keysRef[i]];
+    const value = objects[valuesRef[i]];
+    if (typeof key === 'string') {
+      result[key] = value;
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Extract strings from NSKeyedArchiver objects array as dictionary keys
+ */
+export function extractCapabilityStrings(objects: any[]): PlistDictionary {
+  const result: PlistDictionary = {};
+
+  // Start from index 1 because index 0 is always '$null' in NSKeyedArchiver format
+  for (let i = 1; i < objects.length; i++) {
+    const obj = objects[i];
+    if (typeof obj === 'string' && obj !== '$null') {
+      result[obj] = true;
+    }
+  }
+
+  return result;
+}

package/src/services.ts

@@ -4,6 +4,7 @@ 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 {
+  DVTServiceWithConnection,
   DiagnosticsServiceWithConnection,
   MisagentServiceWithConnection,
   MobileConfigServiceWithConnection,
@@ -16,6 +17,9 @@ import type {
 } from './lib/types.js';
 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 { ConditionInducer } from './services/ios/dvt/instruments/condition-inducer.js';
+import { LocationSimulation } from './services/ios/dvt/instruments/location-simulation.js';
 import { MisagentService } from './services/ios/misagent/index.js';
 import { MobileConfigService } from './services/ios/mobile-config/index.js';
 import MobileImageMounterService from './services/ios/mobile-image-mounter/index.js';
@@ -176,6 +180,35 @@ export async function startWebInspectorService(
   };
 }
 
+export async function startDVTService(
+  udid: string,
+): Promise<DVTServiceWithConnection> {
+  const { remoteXPC, tunnelConnection } = await createRemoteXPCConnection(udid);
+  const dvtServiceDescriptor = remoteXPC.findService(
+    DVTSecureSocketProxyService.RSD_SERVICE_NAME,
+  );
+
+  // Create DVT service instance
+  const dvtService = new DVTSecureSocketProxyService([
+    tunnelConnection.host,
+    parseInt(dvtServiceDescriptor.port, 10),
+  ]);
+
+  // Connect to DVT service
+  await dvtService.connect();
+
+  // Create instrument services
+  const locationSimulation = new LocationSimulation(dvtService);
+  const conditionInducer = new ConditionInducer(dvtService);
+
+  return {
+    remoteXPC: remoteXPC as RemoteXpcConnection,
+    dvtService,
+    locationSimulation,
+    conditionInducer,
+  };
+}
+
 export async function createRemoteXPCConnection(udid: string) {
   const tunnelConnection = await getTunnelInformation(udid);
   const remoteXPC = await startService(