appium-ios-remotexpc 0.0.2 → 0.0.4

package/build/src/lib/apple-tv/utils/buffer-utils.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Converts a non-negative bigint to a fixed-length Buffer in big-endian format.
+ *
+ * @param value - The bigint value to convert (must be non-negative).
+ * @param length - The target buffer length in bytes.
+ * @returns A Buffer representing the bigint, padded to the specified length.
+ *
+ * @throws {RangeError} If the value is negative or doesn't fit in the specified length.
+ */
+export declare function bigIntToBuffer(value: bigint, length: number): Buffer;
+/**
+ * Converts a Buffer into a bigint by interpreting it as a big-endian hexadecimal number.
+ *
+ * @param buffer - The input Buffer.
+ * @returns A bigint representing the numeric value of the buffer.
+ */
+export declare function bufferToBigInt(buffer: Buffer): bigint;
+/**
+ * Converts a non-negative bigint into a minimal-length Buffer in big-endian format.
+ * No unnecessary leading zero bytes will be included.
+ *
+ * @param value - The bigint value to convert (must be non-negative).
+ * @returns A Buffer representing the bigint with minimal byte length.
+ *
+ * @throws {RangeError} If the value is negative.
+ */
+export declare function bigIntToMinimalBuffer(value: bigint): Buffer;
+/**
+ * Computes modular exponentiation: (base ^ exponent) % modulus.
+ * Efficiently handles large numbers using the binary exponentiation method.
+ *
+ * @param base - The base number.
+ * @param exponent - The exponent (must be non-negative).
+ * @param modulus - The modulus (must be non-zero).
+ * @returns The result of (base ** exponent) modulo modulus.
+ *
+ * @throws {RangeError} If the exponent is negative or the modulus is zero.
+ */
+export declare function modPow(base: bigint, exponent: bigint, modulus: bigint): bigint;
+//# sourceMappingURL=buffer-utils.d.ts.map

package/build/src/lib/apple-tv/utils/buffer-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"buffer-utils.d.ts","sourceRoot":"","sources":["../../../../../src/lib/apple-tv/utils/buffer-utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAepE;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAErD;AAED;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAO3D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,MAAM,CACpB,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,GACd,MAAM,CAoBR"}

package/build/src/lib/apple-tv/utils/buffer-utils.js

@@ -0,0 +1,76 @@
+/**
+ * Converts a non-negative bigint to a fixed-length Buffer in big-endian format.
+ *
+ * @param value - The bigint value to convert (must be non-negative).
+ * @param length - The target buffer length in bytes.
+ * @returns A Buffer representing the bigint, padded to the specified length.
+ *
+ * @throws {RangeError} If the value is negative or doesn't fit in the specified length.
+ */
+export function bigIntToBuffer(value, length) {
+    if (value < 0n) {
+        throw new RangeError('Negative values not supported');
+    }
+    const hex = value.toString(16);
+    const byteLength = Math.ceil(hex.length / 2);
+    if (byteLength > length) {
+        throw new RangeError(`Value 0x${hex} is too large to fit in ${length} bytes`);
+    }
+    const paddedHex = hex.padStart(length * 2, '0');
+    return Buffer.from(paddedHex, 'hex');
+}
+/**
+ * Converts a Buffer into a bigint by interpreting it as a big-endian hexadecimal number.
+ *
+ * @param buffer - The input Buffer.
+ * @returns A bigint representing the numeric value of the buffer.
+ */
+export function bufferToBigInt(buffer) {
+    return BigInt('0x' + buffer.toString('hex'));
+}
+/**
+ * Converts a non-negative bigint into a minimal-length Buffer in big-endian format.
+ * No unnecessary leading zero bytes will be included.
+ *
+ * @param value - The bigint value to convert (must be non-negative).
+ * @returns A Buffer representing the bigint with minimal byte length.
+ *
+ * @throws {RangeError} If the value is negative.
+ */
+export function bigIntToMinimalBuffer(value) {
+    if (value < 0n) {
+        throw new RangeError('Negative values not supported');
+    }
+    const hex = value.toString(16);
+    const paddedHex = hex.length % 2 === 0 ? hex : '0' + hex;
+    return Buffer.from(paddedHex, 'hex');
+}
+/**
+ * Computes modular exponentiation: (base ^ exponent) % modulus.
+ * Efficiently handles large numbers using the binary exponentiation method.
+ *
+ * @param base - The base number.
+ * @param exponent - The exponent (must be non-negative).
+ * @param modulus - The modulus (must be non-zero).
+ * @returns The result of (base ** exponent) modulo modulus.
+ *
+ * @throws {RangeError} If the exponent is negative or the modulus is zero.
+ */
+export function modPow(base, exponent, modulus) {
+    if (modulus === 0n) {
+        throw new RangeError('Modulus must be non-zero');
+    }
+    if (exponent < 0n) {
+        throw new RangeError('Negative exponents not supported');
+    }
+    let result = 1n;
+    base = base % modulus;
+    while (exponent > 0n) {
+        if (exponent % 2n === 1n) {
+            result = (result * base) % modulus;
+        }
+        exponent = exponent / 2n;
+        base = (base * base) % modulus;
+    }
+    return result;
+}

package/build/src/lib/apple-tv/utils/index.d.ts

@@ -0,0 +1,3 @@
+export * from './buffer-utils.js';
+export * from './uuid-generator.js';
+//# sourceMappingURL=index.d.ts.map

package/build/src/lib/apple-tv/utils/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/lib/apple-tv/utils/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC"}

package/build/src/lib/apple-tv/utils/index.js

@@ -0,0 +1,2 @@
+export * from './buffer-utils.js';
+export * from './uuid-generator.js';

package/build/src/lib/apple-tv/utils/uuid-generator.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Generates a deterministic UUIDv3 (MD5-based) from a hostname string.
+ * This mimics DNS-based UUID generation using the standard DNS namespace UUID.
+ *
+ * @param hostname - The host string to be converted to a UUID
+ * @returns A UUIDv3 string in uppercase
+ */
+export declare function generateHostId(hostname: string): string;
+//# sourceMappingURL=uuid-generator.d.ts.map

package/build/src/lib/apple-tv/utils/uuid-generator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"uuid-generator.d.ts","sourceRoot":"","sources":["../../../../../src/lib/apple-tv/utils/uuid-generator.ts"],"names":[],"mappings":"AAKA;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CA8BvD"}

package/build/src/lib/apple-tv/utils/uuid-generator.js

@@ -0,0 +1,36 @@
+import { createHash } from 'node:crypto';
+// UUID namespace for DNS, per RFC 4122
+const NAMESPACE_DNS = '6ba7b810-9dad-11d1-80b4-00c04fd430c8';
+/**
+ * Generates a deterministic UUIDv3 (MD5-based) from a hostname string.
+ * This mimics DNS-based UUID generation using the standard DNS namespace UUID.
+ *
+ * @param hostname - The host string to be converted to a UUID
+ * @returns A UUIDv3 string in uppercase
+ */
+export function generateHostId(hostname) {
+    if (typeof hostname !== 'string' || hostname.length === 0) {
+        throw new TypeError('Hostname must be a non-empty string');
+    }
+    const namespaceBytes = Buffer.from(NAMESPACE_DNS.replace(/-/g, ''), 'hex');
+    // Hash the namespace and the hostname using MD5
+    const hash = createHash('md5');
+    hash.update(namespaceBytes);
+    hash.update(hostname, 'utf8');
+    const hashBytes = hash.digest();
+    // Set UUID version to 3 (MD5)
+    hashBytes[6] = (hashBytes[6] & 0x0f) | 0x30;
+    // Set UUID variant to RFC 4122
+    hashBytes[8] = (hashBytes[8] & 0x3f) | 0x80;
+    // Convert to UUID string format
+    const uuid = [
+        hashBytes.subarray(0, 4).toString('hex'),
+        hashBytes.subarray(4, 6).toString('hex'),
+        hashBytes.subarray(6, 8).toString('hex'),
+        hashBytes.subarray(8, 10).toString('hex'),
+        hashBytes.subarray(10, 16).toString('hex'),
+    ]
+        .join('-')
+        .toUpperCase();
+    return uuid;
+}

package/build/src/lib/lockdown/index.d.ts

@@ -0,0 +1,87 @@
+import { Socket } from 'node:net';
+import { type ConnectionOptions, TLSSocket } from 'tls';
+import { BasePlistService } from '../../base-plist-service.js';
+import type { PlistMessage, PlistValue } from '../types.js';
+import { RelayService } from '../usbmux/index.js';
+interface DeviceProperties {
+    ConnectionSpeed: number;
+    ConnectionType: string;
+    DeviceID: number;
+    LocationID: number;
+    ProductID: number;
+    SerialNumber: string;
+    USBSerialNumber: string;
+}
+interface Device {
+    DeviceID: number;
+    MessageType: string;
+    Properties: DeviceProperties;
+}
+interface LockdownServiceInfo {
+    lockdownService: LockdownService;
+    device: Device;
+}
+interface SessionInfo {
+    sessionID: string;
+    enableSessionSSL: boolean;
+}
+export declare class LockdownService extends BasePlistService {
+    private readonly udid;
+    private tlsService?;
+    private isTLS;
+    private tlsUpgradePromise?;
+    private _relayService?;
+    private readonly tlsManager;
+    private readonly deviceManager;
+    constructor(socket: Socket, udid: string, autoSecure?: boolean);
+    /**
+     * Starts a lockdown session
+     */
+    startSession(hostID: string, systemBUID: string, timeout?: number): Promise<SessionInfo>;
+    /**
+     * Attempts to upgrade the connection to TLS
+     */
+    tryUpgradeToTLS(): Promise<void>;
+    /**
+     * Gets the current socket (TLS or regular)
+     */
+    getSocket(): Socket | TLSSocket;
+    /**
+     * Sends a message and receives a response
+     */
+    sendAndReceive(msg: Record<string, PlistValue>, timeout?: number): Promise<PlistMessage>;
+    /**
+     * Closes the service and associated resources
+     */
+    close(): void;
+    /**
+     * Sets the relay service for this lockdown instance
+     */
+    set relayService(relay: RelayService);
+    /**
+     * Gets the relay service for this lockdown instance
+     */
+    get relayService(): RelayService | undefined;
+    /**
+     * Waits for TLS upgrade to complete if in progress
+     */
+    waitForTLSUpgrade(): Promise<void>;
+    /**
+     * Stops the relay service with an optional custom message
+     */
+    stopRelayService(message?: string): void;
+    private validatePairRecord;
+    private performTLSUpgrade;
+    private closeSocket;
+}
+export declare class LockdownServiceFactory {
+    private readonly deviceManager;
+    /**
+     * Creates a LockdownService for a specific device UDID
+     */
+    createByUDID(udid: string, port?: number, autoSecure?: boolean): Promise<LockdownServiceInfo>;
+}
+export declare function createLockdownServiceByUDID(udid: string, port?: number, autoSecure?: boolean): Promise<LockdownServiceInfo>;
+export declare function upgradeSocketToTLS(socket: Socket, tlsOptions?: Partial<ConnectionOptions>): Promise<TLSSocket>;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/build/src/lib/lockdown/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/lib/lockdown/index.ts"],"names":[],"mappings":"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"}

package/build/src/lib/lockdown/index.js

@@ -0,0 +1,324 @@
+import { logger } from '@appium/support';
+import { Socket } from 'node:net';
+import tls, { TLSSocket } from 'tls';
+import { BasePlistService } from '../../base-plist-service.js';
+import {} from '../pair-record/index.js';
+import { PlistService } from '../plist/plist-service.js';
+import { RelayService, createUsbmux } from '../usbmux/index.js';
+const log = logger.getLogger('Lockdown');
+// Constants
+const LABEL = 'appium-internal';
+const DEFAULT_TIMEOUT = 5000;
+const DEFAULT_LOCKDOWN_PORT = 62078;
+const DEFAULT_RELAY_PORT = 2222;
+// Error classes for better error handling
+class LockdownError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'LockdownError';
+    }
+}
+class TLSUpgradeError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'TLSUpgradeError';
+    }
+}
+class DeviceNotFoundError extends Error {
+    constructor(udid) {
+        super(`Device with UDID ${udid} not found`);
+        this.name = 'DeviceNotFoundError';
+    }
+}
+// TLS Manager for handling TLS operations
+class TLSManager {
+    log = logger.getLogger('TLSManager');
+    /**
+     * Upgrades a socket to TLS
+     */
+    async upgradeSocketToTLS(socket, tlsOptions = {}) {
+        return new Promise((resolve, reject) => {
+            socket.pause();
+            this.log.debug('Upgrading socket to TLS...');
+            const secure = tls.connect({
+                socket,
+                rejectUnauthorized: false,
+                minVersion: 'TLSv1.2',
+                ...tlsOptions,
+            }, () => {
+                this.log.info('TLS handshake completed');
+                resolve(secure);
+            });
+            secure.on('error', (err) => {
+                this.log.error(`TLS socket error: ${err}`);
+                reject(new TLSUpgradeError(`TLS socket error: ${err.message}`));
+            });
+            socket.on('error', (err) => {
+                this.log.error(`Underlying socket error during TLS: ${err}`);
+                reject(new TLSUpgradeError(`Socket error during TLS: ${err.message}`));
+            });
+        });
+    }
+}
+// Device Manager for handling device operations
+class DeviceManager {
+    log = logger.getLogger('DeviceManager');
+    /**
+     * Lists all connected devices
+     */
+    async listDevices() {
+        const usbmux = await createUsbmux();
+        try {
+            this.log.debug('Listing connected devices...');
+            const devices = await usbmux.listDevices();
+            this.log.debug(`Found ${devices.length} devices: ${devices.map((d) => d.Properties.SerialNumber).join(', ')}`);
+            return devices;
+        }
+        finally {
+            await this.closeUsbmux(usbmux);
+        }
+    }
+    /**
+     * Finds a device by UDID
+     */
+    async findDeviceByUDID(udid) {
+        const devices = await this.listDevices();
+        if (!devices || devices.length === 0) {
+            throw new LockdownError('No devices connected');
+        }
+        const device = devices.find((d) => d.Properties.SerialNumber === udid);
+        if (!device) {
+            throw new DeviceNotFoundError(udid);
+        }
+        this.log.info(`Found device: DeviceID=${device.DeviceID}, SerialNumber=${device.Properties.SerialNumber}, ConnectionType=${device.Properties.ConnectionType}`);
+        return device;
+    }
+    /**
+     * Reads pair record for a device
+     */
+    async readPairRecord(udid) {
+        this.log.debug(`Retrieving pair record for UDID: ${udid}`);
+        const usbmux = await createUsbmux();
+        try {
+            const record = await usbmux.readPairRecord(udid);
+            if (!record?.HostCertificate || !record.HostPrivateKey) {
+                throw new LockdownError('Pair record missing certificate or key');
+            }
+            this.log.info('Pair record retrieved successfully');
+            return record;
+        }
+        catch (err) {
+            this.log.error(`Error getting pair record: ${err}`);
+            throw err;
+        }
+        finally {
+            await this.closeUsbmux(usbmux);
+        }
+    }
+    async closeUsbmux(usbmux) {
+        try {
+            await usbmux.close();
+        }
+        catch (err) {
+            this.log.error(`Error closing usbmux: ${err}`);
+        }
+    }
+}
+// Main LockdownService class
+export class LockdownService extends BasePlistService {
+    udid;
+    tlsService;
+    isTLS = false;
+    tlsUpgradePromise;
+    _relayService;
+    tlsManager = new TLSManager();
+    deviceManager = new DeviceManager();
+    constructor(socket, udid, autoSecure = true) {
+        super(socket);
+        this.udid = udid;
+        log.info(`LockdownService initialized for UDID: ${udid}`);
+        if (autoSecure) {
+            this.tlsUpgradePromise = this.tryUpgradeToTLS().catch((err) => log.warn(`Auto TLS upgrade failed: ${err.message}`));
+        }
+    }
+    /**
+     * Starts a lockdown session
+     */
+    async startSession(hostID, systemBUID, timeout = DEFAULT_TIMEOUT) {
+        log.debug(`Starting lockdown session with HostID: ${hostID}`);
+        const request = {
+            Label: LABEL,
+            Request: 'StartSession',
+            HostID: hostID,
+            SystemBUID: systemBUID,
+        };
+        const response = (await this.sendAndReceive(request, timeout));
+        if (response.Request === 'StartSession' && response.SessionID) {
+            const sessionInfo = {
+                sessionID: String(response.SessionID),
+                enableSessionSSL: Boolean(response.EnableSessionSSL),
+            };
+            log.info(`Lockdown session started, SessionID: ${sessionInfo.sessionID}`);
+            return sessionInfo;
+        }
+        throw new LockdownError(`Unexpected session data: ${JSON.stringify(response)}`);
+    }
+    /**
+     * Attempts to upgrade the connection to TLS
+     */
+    async tryUpgradeToTLS() {
+        try {
+            const pairRecord = await this.deviceManager.readPairRecord(this.udid);
+            if (!this.validatePairRecord(pairRecord)) {
+                log.warn('Invalid pair record for TLS upgrade');
+                return;
+            }
+            const sessionInfo = await this.startSession(pairRecord.HostID, pairRecord.SystemBUID);
+            if (!sessionInfo.enableSessionSSL) {
+                log.info('Device did not request TLS upgrade. Continuing unencrypted.');
+                return;
+            }
+            await this.performTLSUpgrade(pairRecord);
+        }
+        catch (err) {
+            log.error(`TLS upgrade failed: ${err}`);
+            throw err;
+        }
+    }
+    /**
+     * Gets the current socket (TLS or regular)
+     */
+    getSocket() {
+        return this.isTLS && this.tlsService
+            ? this.tlsService.getSocket()
+            : this.getPlistService().getSocket();
+    }
+    /**
+     * Sends a message and receives a response
+     */
+    async sendAndReceive(msg, timeout = DEFAULT_TIMEOUT) {
+        const service = this.isTLS && this.tlsService ? this.tlsService : this._plistService;
+        return service.sendPlistAndReceive(msg, timeout);
+    }
+    /**
+     * Closes the service and associated resources
+     */
+    close() {
+        log.info('Closing LockdownService connections');
+        try {
+            this.closeSocket();
+            this.stopRelayService();
+        }
+        catch (err) {
+            log.error(`Error during close: ${err}`);
+            throw err;
+        }
+    }
+    /**
+     * Sets the relay service for this lockdown instance
+     */
+    set relayService(relay) {
+        this._relayService = relay;
+    }
+    /**
+     * Gets the relay service for this lockdown instance
+     */
+    get relayService() {
+        return this._relayService;
+    }
+    /**
+     * Waits for TLS upgrade to complete if in progress
+     */
+    async waitForTLSUpgrade() {
+        if (this.tlsUpgradePromise) {
+            await this.tlsUpgradePromise;
+        }
+    }
+    /**
+     * Stops the relay service with an optional custom message
+     */
+    stopRelayService(message = 'Stopping relay server associated with LockdownService') {
+        const relay = this.relayService;
+        if (relay) {
+            log.info(message);
+            (async () => {
+                try {
+                    await relay.stop();
+                    log.info('Relay server stopped successfully');
+                }
+                catch (err) {
+                    log.error(`Error stopping relay server: ${err}`);
+                }
+            })();
+        }
+    }
+    validatePairRecord(record) {
+        return Boolean(record?.HostCertificate &&
+            record.HostPrivateKey &&
+            record.HostID &&
+            record.SystemBUID);
+    }
+    async performTLSUpgrade(pairRecord) {
+        const tlsConfig = {
+            cert: pairRecord.HostCertificate,
+            key: pairRecord.HostPrivateKey,
+        };
+        const tlsSocket = await this.tlsManager.upgradeSocketToTLS(this.getSocket(), tlsConfig);
+        this.tlsService = new PlistService(tlsSocket);
+        this.isTLS = true;
+        log.info('Successfully upgraded connection to TLS');
+    }
+    closeSocket() {
+        if (this.isTLS && this.tlsService) {
+            this.tlsService.close();
+        }
+        else {
+            super.close();
+        }
+    }
+}
+// Factory class for creating LockdownService instances
+export class LockdownServiceFactory {
+    deviceManager = new DeviceManager();
+    /**
+     * Creates a LockdownService for a specific device UDID
+     */
+    async createByUDID(udid, port = DEFAULT_LOCKDOWN_PORT, autoSecure = true) {
+        log.info(`Creating LockdownService for UDID: ${udid}`);
+        // Find the device
+        const device = await this.deviceManager.findDeviceByUDID(udid);
+        // Create relay service
+        const relay = new RelayService(device.DeviceID, port, DEFAULT_RELAY_PORT);
+        await relay.start();
+        let service;
+        try {
+            // Connect through the relay
+            const socket = await relay.connect();
+            log.debug('Socket connected, creating LockdownService');
+            // Create the lockdown service
+            service = new LockdownService(socket, udid, autoSecure);
+            service.relayService = relay;
+            // Wait for TLS upgrade if enabled
+            if (autoSecure) {
+                log.debug('Waiting for TLS upgrade to complete...');
+                await service.waitForTLSUpgrade();
+            }
+            return { lockdownService: service, device };
+        }
+        catch (err) {
+            // Clean up relay on error
+            service?.stopRelayService('Stopping relay after failure');
+            throw err;
+        }
+    }
+}
+// Export factory function for backward compatibility
+export async function createLockdownServiceByUDID(udid, port = DEFAULT_LOCKDOWN_PORT, autoSecure = true) {
+    const factory = new LockdownServiceFactory();
+    return factory.createByUDID(udid, port, autoSecure);
+}
+// Export the TLS upgrade function for external use
+export function upgradeSocketToTLS(socket, tlsOptions = {}) {
+    const tlsManager = new TLSManager();
+    return tlsManager.upgradeSocketToTLS(socket, tlsOptions);
+}

package/build/src/lib/pair-record/index.d.ts

@@ -0,0 +1,3 @@
+import { type PairRecord, getPairRecord, processPlistResponse, savePairRecord } from './pair-record.js';
+export { getPairRecord, processPlistResponse, savePairRecord, type PairRecord };
+//# sourceMappingURL=index.d.ts.map

package/build/src/lib/pair-record/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/lib/pair-record/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,UAAU,EACf,aAAa,EACb,oBAAoB,EACpB,cAAc,EACf,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EAAE,aAAa,EAAE,oBAAoB,EAAE,cAAc,EAAE,KAAK,UAAU,EAAE,CAAC"}

package/build/src/lib/pair-record/index.js

@@ -0,0 +1,2 @@
+import { getPairRecord, processPlistResponse, savePairRecord, } from './pair-record.js';
+export { getPairRecord, processPlistResponse, savePairRecord };

package/build/src/lib/pair-record/pair-record.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Interface defining the structure of a pair record.
+ */
+export interface PairRecord {
+    HostID: string | null;
+    SystemBUID: string | null;
+    HostCertificate: string | null;
+    HostPrivateKey: string | null;
+    DeviceCertificate: string | null;
+    RootCertificate: string | null;
+    RootPrivateKey: string | null;
+    WiFiMACAddress: string | null;
+    EscrowBag: string | null;
+}
+/**
+ * Interface for the raw response from plist.parsePlist
+ */
+export interface RawPairRecordResponse {
+    HostID: string;
+    SystemBUID: string;
+    HostCertificate: Buffer;
+    HostPrivateKey: Buffer;
+    DeviceCertificate: Buffer;
+    RootCertificate: Buffer;
+    RootPrivateKey: Buffer;
+    WiFiMACAddress: string;
+    EscrowBag: Buffer;
+}
+/**
+ * Processes raw response from plist.parsePlist and formats it into a proper pair-record
+ * @param response - Response from plist.parsePlist(data.payload.PairRecordData)
+ * @returns Formatted pair-record object with properly structured data
+ */
+export declare function processPlistResponse(response: RawPairRecordResponse): PairRecord;
+/**
+ * Saves a pair record to the filesystem.
+ * @param udid - Device UDID.
+ * @param pairRecord - Pair record to save.
+ * @returns Promise that resolves when record is saved.
+ */
+export declare function savePairRecord(udid: string, pairRecord: PairRecord): Promise<void>;
+/**
+ * Gets a saved pair record from the filesystem.
+ * @param udid - Device UDID.
+ * @returns Promise that resolves with the pair record or null if not found.
+ */
+export declare function getPairRecord(udid: string): Promise<PairRecord | null>;
+//# sourceMappingURL=pair-record.d.ts.map

package/build/src/lib/pair-record/pair-record.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pair-record.d.ts","sourceRoot":"","sources":["../../../../src/lib/pair-record/pair-record.ts"],"names":[],"mappings":"AAMA;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,EAAE,MAAM,CAAC;IACxB,cAAc,EAAE,MAAM,CAAC;IACvB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,eAAe,EAAE,MAAM,CAAC;IACxB,cAAc,EAAE,MAAM,CAAC;IACvB,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;CACnB;AAWD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,qBAAqB,GAC9B,UAAU,CAyBZ;AAUD;;;;;GAKG;AACH,wBAAsB,cAAc,CAClC,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,UAAU,GACrB,OAAO,CAAC,IAAI,CAAC,CAef;AAED;;;;GAIG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAc5E"}