appium-ios-remotexpc 0.3.3 → 0.4.0

package/build/src/services/ios/mobile-image-mounter/index.js

@@ -0,0 +1,363 @@
+import { logger } from '@appium/support';
+import { createHash } from 'crypto';
+import { Stats, promises as fs } from 'fs';
+import { performance } from 'perf_hooks';
+import { Readable } from 'stream';
+import { parseXmlPlist } from '../../../lib/plist/index.js';
+import { getManifestFromTSS } from '../../../lib/tss/index.js';
+import { ServiceConnection } from '../../../service-connection.js';
+import { BaseService } from '../base-service.js';
+const log = logger.getLogger('MobileImageMounterService');
+/**
+ * MobileImageMounterService provides an API to:
+ * - Mount Developer Disk Images on iOS devices
+ * - Lookup mounted images and their signatures
+ * - Check if personalized images are mounted
+ * - Unmount images when needed
+ */
+class MobileImageMounterService extends BaseService {
+    static RSD_SERVICE_NAME = 'com.apple.mobile.mobile_image_mounter.shim.remote';
+    // Constants
+    static FILE_TYPE_IMAGE = 'image';
+    static FILE_TYPE_BUILD_MANIFEST = 'build_manifest';
+    static FILE_TYPE_TRUST_CACHE = 'trust_cache';
+    static IMAGE_TYPE = 'Personalized';
+    static MOUNT_PATH = '/System/Developer';
+    static UPLOAD_IMAGE_TIMEOUT = 20000;
+    // Connection cache
+    connection = null;
+    constructor(address) {
+        super(address);
+    }
+    /**
+     * Clean up resources when service is no longer needed
+     */
+    async cleanup() {
+        this.closeConnection();
+    }
+    /**
+     * Lookup mounted images by type
+     * @param imageType Type of image to lookup (defaults to 'Personalized')
+     * @returns Array of signatures of mounted images
+     */
+    async lookup(imageType = MobileImageMounterService.IMAGE_TYPE) {
+        const response = (await this.sendRequest({
+            Command: 'LookupImage',
+            ImageType: imageType,
+        }));
+        const signatures = response.ImageSignature || [];
+        return signatures.filter(Buffer.isBuffer);
+    }
+    /**
+     * Check if personalized image is mounted
+     * @returns True if personalized image is mounted
+     */
+    async isPersonalizedImageMounted() {
+        try {
+            return (await this.lookup()).length > 0;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Mount personalized image for device (iOS >= 17)
+     * @param imageFilePath Path to the image file (.dmg)
+     * @param buildManifestFilePath Path to the build manifest file (.plist)
+     * @param trustCacheFilePath Path to the trust cache file (.trustcache)
+     * @param infoPlist Optional info plist dictionary
+     */
+    async mount(imageFilePath, buildManifestFilePath, trustCacheFilePath, infoPlist) {
+        if (await this.isPersonalizedImageMounted()) {
+            log.info('Personalized image is already mounted');
+            return;
+        }
+        const start = performance.now();
+        // Validate files and read content
+        await Promise.all([
+            this.assertIsFile(imageFilePath, MobileImageMounterService.FILE_TYPE_IMAGE),
+            this.assertIsFile(buildManifestFilePath, MobileImageMounterService.FILE_TYPE_BUILD_MANIFEST),
+            this.assertIsFile(trustCacheFilePath, MobileImageMounterService.FILE_TYPE_TRUST_CACHE),
+        ]);
+        const [image, trustCache, buildManifestContent] = await Promise.all([
+            fs.readFile(imageFilePath),
+            fs.readFile(trustCacheFilePath),
+            fs.readFile(buildManifestFilePath, 'utf8'),
+        ]);
+        const buildManifest = parseXmlPlist(buildManifestContent);
+        const manifest = await this.getOrRetrieveManifestFromTSS(image, buildManifest);
+        await this.uploadImage(MobileImageMounterService.IMAGE_TYPE, image, manifest);
+        const extras = {
+            ImageTrustCache: trustCache,
+        };
+        if (infoPlist) {
+            extras.ImageInfoPlist = infoPlist;
+        }
+        await this.mountImage(MobileImageMounterService.IMAGE_TYPE, manifest, extras);
+        const end = performance.now();
+        log.info(`Successfully mounted personalized image in ${(end - start).toFixed(2)} ms`);
+    }
+    /**
+     * Unmount image from device
+     * @param mountPath Mount path to unmount (defaults to '/System/Developer')
+     */
+    async unmountImage(mountPath = MobileImageMounterService.MOUNT_PATH) {
+        const response = (await this.sendRequest({
+            Command: 'UnmountImage',
+            MountPath: mountPath,
+        }));
+        if (response.Error === 'UnknownCommand') {
+            throw new Error('Unmount command is not supported on this iOS version');
+        }
+        if (response.DetailedError?.includes('There is no matching entry')) {
+            throw new Error(`No mounted image found at path: ${mountPath}`);
+        }
+        if (response.Error === 'InternalError') {
+            throw new Error(`Internal error occurred while unmounting: ${JSON.stringify(response)}`);
+        }
+        this.checkIfError(response);
+        log.info(`Successfully unmounted image from ${mountPath}`);
+    }
+    /**
+     * Query developer mode status (iOS 16+)
+     * @returns True if developer mode is enabled (defaults to true for older iOS)
+     */
+    async queryDeveloperModeStatus() {
+        try {
+            const response = await this.sendRequest({
+                Command: 'QueryDeveloperModeStatus',
+            });
+            this.checkIfError(response);
+            return Boolean(response.DeveloperModeStatus);
+        }
+        catch {
+            return true; // Default for older iOS versions
+        }
+    }
+    /**
+     * Query personalization nonce for personalized images
+     * @param personalizedImageType Optional personalized image type
+     * @returns Personalization nonce as Buffer
+     */
+    async queryNonce(personalizedImageType) {
+        const request = { Command: 'QueryNonce' };
+        if (personalizedImageType) {
+            request.PersonalizedImageType = personalizedImageType;
+        }
+        const response = await this.sendRequest(request);
+        this.checkIfError(response);
+        const nonce = response.PersonalizationNonce;
+        if (!Buffer.isBuffer(nonce)) {
+            throw new Error('Invalid nonce received from device');
+        }
+        return nonce;
+    }
+    /**
+     * Query personalization identifiers from the device
+     * @returns Personalization identifiers dictionary
+     */
+    async queryPersonalizationIdentifiers() {
+        const response = await this.sendRequest({
+            Command: 'QueryPersonalizationIdentifiers',
+        });
+        this.checkIfError(response);
+        return response.PersonalizationIdentifiers;
+    }
+    /**
+     * Copy devices info (only for mounted images)
+     * @returns List of mounted devices
+     */
+    async copyDevices() {
+        const response = await this.sendRequest({ Command: 'CopyDevices' });
+        return response.EntryList || [];
+    }
+    /**
+     * Query personalization manifest from device
+     * @param imageType The image type
+     * @param signature The image signature/hash
+     * @returns Personalization manifest as Buffer
+     */
+    async queryPersonalizationManifest(imageType, signature) {
+        try {
+            const response = await this.sendRequest({
+                Command: 'QueryPersonalizationManifest',
+                PersonalizedImageType: imageType,
+                ImageType: imageType,
+                ImageSignature: signature,
+            });
+            this.checkIfError(response);
+            const manifest = response.ImageSignature;
+            if (!manifest || !Buffer.isBuffer(manifest)) {
+                throw new Error('MissingManifestError: Personalization manifest not found on device');
+            }
+            return manifest;
+        }
+        catch (error) {
+            if (error instanceof Error &&
+                error.message.includes('MissingManifestError')) {
+                throw error;
+            }
+            throw new Error('MissingManifestError: Personalization manifest not found on device');
+        }
+    }
+    /**
+     * Upload image to device
+     * @param imageType The image type
+     * @param image The image data
+     * @param signature The image signature/manifest
+     * @param timeout Optional timeout for upload operation (defaults to 20000ms)
+     */
+    async uploadImage(imageType, image, signature, timeout = MobileImageMounterService.UPLOAD_IMAGE_TIMEOUT) {
+        const receiveBytesResult = (await this.sendRequest({
+            Command: 'ReceiveBytes',
+            ImageType: imageType,
+            ImageSize: image.length,
+            ImageSignature: signature,
+        }));
+        this.checkIfError(receiveBytesResult);
+        if (receiveBytesResult.Status !== 'ReceiveBytesAck') {
+            throw new Error(`Unexpected return from mobile_image_mounter: ${JSON.stringify(receiveBytesResult)}`);
+        }
+        const conn = await this.connectToMobileImageMounterService();
+        const socket = conn.getSocket();
+        await new Promise((resolve, reject) => {
+            socket.write(image, (error) => error ? reject(error) : resolve());
+        });
+        const uploadResult = await conn.receive(timeout);
+        if (uploadResult.Status !== 'Complete') {
+            throw new Error(`Image upload failed: ${JSON.stringify(uploadResult)}`);
+        }
+        log.debug('Image uploaded successfully');
+    }
+    /**
+     * Mount image on device
+     * @param imageType The image type
+     * @param signature The image signature/manifest
+     * @param extras Additional parameters for mounting
+     */
+    async mountImage(imageType, signature, extras) {
+        const request = {
+            Command: 'MountImage',
+            ImageType: imageType,
+            ImageSignature: signature,
+            ...extras,
+        };
+        const response = (await this.sendRequest(request));
+        if (response.DetailedError?.includes('is already mounted')) {
+            log.info('Image was already mounted');
+            return;
+        }
+        if (response.DetailedError?.includes('Developer mode is not enabled')) {
+            throw new Error('Developer mode is not enabled on this device');
+        }
+        this.checkIfError(response);
+        if (response.Status !== 'Complete') {
+            throw new Error(`Mount image failed: ${JSON.stringify(response)}`);
+        }
+        log.debug('Image mounted successfully');
+    }
+    async sendRequest(request, timeout) {
+        const isNewConnection = !this.connection || this.isConnectionDestroyed();
+        const conn = await this.connectToMobileImageMounterService();
+        const res = await conn.sendPlistRequest(request, timeout);
+        if (isNewConnection && res?.Request === 'StartService') {
+            return await conn.receive();
+        }
+        return res;
+    }
+    /**
+     * Calculate hash of a buffer asynchronously
+     * @param buffer The buffer to hash
+     * @returns Promise resolving to the hash digest
+     */
+    async hashLargeBufferAsync(buffer) {
+        return new Promise((resolve, reject) => {
+            const hash = createHash('sha384');
+            const stream = Readable.from(buffer);
+            stream.on('data', (chunk) => {
+                hash.update(chunk);
+            });
+            stream.on('end', () => {
+                resolve(hash.digest());
+            });
+            stream.on('error', (err) => {
+                reject(err);
+            });
+        });
+    }
+    async getOrRetrieveManifestFromTSS(image, buildManifest) {
+        try {
+            const imageHash = await this.hashLargeBufferAsync(image);
+            const manifest = await this.queryPersonalizationManifest('DeveloperDiskImage', imageHash);
+            log.debug('Successfully retrieved existing personalization manifest from device');
+            return manifest;
+        }
+        catch (error) {
+            if (error.message?.includes('MissingManifestError')) {
+                log.debug('Personalization manifest not found on device, using TSS...');
+                const identifiers = await this.queryPersonalizationIdentifiers();
+                const ecid = identifiers.UniqueChipID;
+                if (!ecid) {
+                    throw new Error('Could not retrieve device ECID from personalization identifiers');
+                }
+                const manifest = await getManifestFromTSS(ecid, buildManifest, () => this.queryPersonalizationIdentifiers(), (type) => this.queryNonce(type));
+                log.debug('Successfully generated manifest from TSS');
+                return manifest;
+            }
+            throw error;
+        }
+    }
+    isConnectionDestroyed() {
+        try {
+            const socket = this.connection.getSocket();
+            return !socket || socket.destroyed;
+        }
+        catch {
+            return true;
+        }
+    }
+    async connectToMobileImageMounterService() {
+        if (this.connection && !this.isConnectionDestroyed()) {
+            return this.connection;
+        }
+        const newConnection = await this.startLockdownService({
+            serviceName: MobileImageMounterService.RSD_SERVICE_NAME,
+            port: this.address[1].toString(),
+        });
+        this.connection = newConnection;
+        return newConnection;
+    }
+    closeConnection() {
+        if (this.connection) {
+            try {
+                this.connection.close();
+            }
+            catch {
+                // Ignore close errors
+            }
+            this.connection = null;
+        }
+    }
+    checkIfError(response) {
+        if (response.Error) {
+            throw new Error(response.Error);
+        }
+    }
+    async assertIsFile(filePath, fileType) {
+        try {
+            const fileStat = await fs.stat(filePath);
+            if (!fileStat.isFile()) {
+                throw new Error(`Expected ${fileType} file, got non-file: ${filePath}`);
+            }
+            return fileStat;
+        }
+        catch (error) {
+            if (error.code === 'ENOENT') {
+                throw new Error(`${fileType} file not found: ${filePath}`);
+            }
+            throw error;
+        }
+    }
+}
+export default MobileImageMounterService;
+export { MobileImageMounterService };

package/build/src/services.d.ts

@@ -1,7 +1,8 @@
 import { RemoteXpcConnection } from './lib/remote-xpc/remote-xpc-connection.js';
-import type { DiagnosticsServiceWithConnection, NotificationProxyServiceWithConnection, SyslogService as SyslogServiceType } from './lib/types.js';
+import type { DiagnosticsServiceWithConnection, MobileImageMounterServiceWithConnection, NotificationProxyServiceWithConnection, SyslogService as SyslogServiceType } from './lib/types.js';
 export declare function startDiagnosticsService(udid: string): Promise<DiagnosticsServiceWithConnection>;
 export declare function startNotificationProxyService(udid: string): Promise<NotificationProxyServiceWithConnection>;
+export declare function startMobileImageMounterService(udid: string): Promise<MobileImageMounterServiceWithConnection>;
 export declare function startSyslogService(udid: string): Promise<SyslogServiceType>;
 export declare function createRemoteXPCConnection(udid: string): Promise<{
     remoteXPC: RemoteXpcConnection;

package/build/src/services.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"services.d.ts","sourceRoot":"","sources":["../../src/services.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,mBAAmB,EAAE,MAAM,2CAA2C,CAAC;AAGhF,OAAO,KAAK,EACV,gCAAgC,EAChC,sCAAsC,EACtC,aAAa,IAAI,iBAAiB,EACnC,MAAM,gBAAgB,CAAC;AAQxB,wBAAsB,uBAAuB,CAC3C,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,gCAAgC,CAAC,CAY3C;AAED,wBAAsB,6BAA6B,CACjD,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,sCAAsC,CAAC,CAYjD;AAED,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,iBAAiB,CAAC,CAG5B;AAED,wBAAsB,yBAAyB,CAAC,IAAI,EAAE,MAAM;;;;;;;;GAO3D"}
+{"version":3,"file":"services.d.ts","sourceRoot":"","sources":["../../src/services.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,mBAAmB,EAAE,MAAM,2CAA2C,CAAC;AAGhF,OAAO,KAAK,EACV,gCAAgC,EAChC,uCAAuC,EACvC,sCAAsC,EACtC,aAAa,IAAI,iBAAiB,EACnC,MAAM,gBAAgB,CAAC;AASxB,wBAAsB,uBAAuB,CAC3C,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,gCAAgC,CAAC,CAY3C;AAED,wBAAsB,6BAA6B,CACjD,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,sCAAsC,CAAC,CAYjD;AAED,wBAAsB,8BAA8B,CAClD,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,uCAAuC,CAAC,CAYlD;AAED,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,iBAAiB,CAAC,CAG5B;AAED,wBAAsB,yBAAyB,CAAC,IAAI,EAAE,MAAM;;;;;;;;GAO3D"}

package/build/src/services.js

@@ -3,6 +3,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 DiagnosticsService from './services/ios/diagnostic-service/index.js';
+import MobileImageMounterService from './services/ios/mobile-image-mounter/index.js';
 import { NotificationProxyService } from './services/ios/notification-proxy/index.js';
 import SyslogService from './services/ios/syslog-service/index.js';
 const APPIUM_XCUITEST_DRIVER_NAME = 'appium-xcuitest-driver';
@@ -29,6 +30,17 @@ export async function startNotificationProxyService(udid) {
         ]),
     };
 }
+export async function startMobileImageMounterService(udid) {
+    const { remoteXPC, tunnelConnection } = await createRemoteXPCConnection(udid);
+    const mobileImageMounterService = remoteXPC.findService(MobileImageMounterService.RSD_SERVICE_NAME);
+    return {
+        remoteXPC: remoteXPC,
+        mobileImageMounterService: new MobileImageMounterService([
+            tunnelConnection.host,
+            parseInt(mobileImageMounterService.port, 10),
+        ]),
+    };
+}
 export async function startSyslogService(udid) {
     const { tunnelConnection } = await createRemoteXPCConnection(udid);
     return new SyslogService([tunnelConnection.host, tunnelConnection.port]);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "appium-ios-remotexpc",
-  "version": "0.3.3",
+  "version": "0.4.0",
   "main": "build/src/index.js",
   "types": "build/src/index.d.ts",
   "type": "module",
@@ -29,6 +29,7 @@
     "test:pair-record": "mocha test/integration/read-pair-record-test.ts --exit --timeout 1m",
     "test:diagnostics": "mocha test/integration/diagnostics-test.ts --exit --timeout 1m",
     "test:notification": "mocha test/integration/notification-proxy-test.ts --exit --timeout 1m",
+    "test:image-mounter": "mocha test/integration/mobile-image-mounter-test.ts --exit --timeout 1m",
     "test:unit": "mocha 'test/unit/**/*.ts' --exit --timeout 2m",
     "test:tunnel-creation": "sudo tsx scripts/test-tunnel-creation.ts",
     "test:tunnel-creation:lsof": "sudo tsx scripts/test-tunnel-creation.ts --keep-open"
@@ -70,8 +71,9 @@
     "@appium/support": "^7.0.0-rc.1",
     "@types/node": "^24.0.10",
     "@xmldom/xmldom": "^0.9.8",
-    "npm-run-all2": "^8.0.4",
-    "appium-ios-tuntap": "^0.x"
+    "appium-ios-tuntap": "^0.x",
+    "axios": "^1.12.0",
+    "npm-run-all2": "^8.0.4"
   },
   "files": [
     "src",

package/src/index.ts

@@ -14,12 +14,14 @@ import { startCoreDeviceProxy } from './services/ios/tunnel-service/index.js';
 
 export type {
   DiagnosticsService,
+  MobileImageMounterService,
   SyslogService,
   SocketInfo,
   TunnelResult,
   TunnelRegistry,
   TunnelRegistryEntry,
   DiagnosticsServiceWithConnection,
+  MobileImageMounterServiceWithConnection,
 } from './lib/types.js';
 export {
   createUsbmux,

package/src/lib/plist/plist-creator.ts

@@ -17,6 +17,10 @@ export function createPlist(obj: PlistDictionary): string {
     if (typeof value === 'string') {
       return `<string>${escapeXml(value)}</string>`;
     }
+    if (Buffer.isBuffer(value)) {
+      const base64Data = value.toString('base64');
+      return `<data>${base64Data}</data>`;
+    }
     if (Array.isArray(value)) {
       return `<array>${value.map((item) => convert(item)).join('')}</array>`;
     }