appium-ios-remotexpc 0.0.1

package/src/base-plist-service.ts

@@ -0,0 +1,83 @@
+import { Socket } from 'node:net';
+
+import {
+  PlistService,
+  type PlistServiceOptions,
+} from './lib/plist/plist-service.js';
+import type { PlistDictionary } from './lib/types.js';
+
+/**
+ * Message type for plist communications
+ */
+type PlistMessage = PlistDictionary;
+
+/**
+ * Base class for services that use PlistService for communication
+ */
+export abstract class BasePlistService {
+  /**
+   * Sends a message and waits for a response
+   * @param message The message to send
+   * @param timeout Timeout in milliseconds
+   * @returns Promise resolving to the response
+   */
+  async sendAndReceive(
+    message: PlistMessage,
+    timeout?: number,
+  ): Promise<PlistMessage> {
+    return this._plistService.sendPlistAndReceive(message, timeout);
+  }
+
+  /**
+   * Closes the underlying connection
+   */
+  public close(): void {
+    this._plistService.close();
+  }
+
+  /**
+   * Gets the PlistService instance
+   * @returns The PlistService instance
+   */
+  protected getPlistService(): PlistService {
+    return this._plistService;
+  }
+
+  /**
+   * The underlying PlistService instance
+   */
+  protected _plistService: PlistService;
+
+  /**
+   * Creates a new BasePlistService
+   * @param plistServiceOrSocket PlistService instance or Socket
+   * @param options Configuration options for PlistService
+   */
+  protected constructor(
+    plistServiceOrSocket: PlistService | Socket,
+    options: PlistServiceOptions = {},
+  ) {
+    if (plistServiceOrSocket instanceof PlistService) {
+      this._plistService = plistServiceOrSocket;
+    } else {
+      this._plistService = new PlistService(plistServiceOrSocket, options);
+    }
+  }
+
+  /**
+   * Sends a message without waiting for a response
+   * @param message The message to send
+   */
+  protected send(message: PlistMessage): void {
+    this._plistService.sendPlist(message);
+  }
+
+  /**
+   * Waits for a message
+   * @param timeout Timeout in milliseconds
+   * @returns Promise resolving to the received message
+   */
+  protected async receive(timeout?: number): Promise<PlistMessage> {
+    return this._plistService.receivePlist(timeout);
+  }
+}

package/src/base-socket-service.ts

@@ -0,0 +1,55 @@
+import { EventEmitter } from 'node:events';
+import { Socket } from 'node:net';
+import { Readable } from 'node:stream';
+
+class BaseSocketService extends EventEmitter {
+  protected _socketClient: Socket;
+  protected _isConnected: boolean = false;
+
+  /**
+   * @param socketClient
+   */
+  constructor(socketClient: Socket) {
+    super();
+    this._socketClient = socketClient;
+
+    // Check if already connected
+    this._isConnected = !socketClient.connecting && !socketClient.destroyed;
+
+    // if not connected and it's a raw socket
+    if (!this._isConnected && socketClient instanceof Socket) {
+      this._socketClient.once('connect', () => {
+        this._isConnected = true;
+        this.emit('connect');
+      });
+    }
+
+    // setup basic error handling
+    this._socketClient.on('error', (err) => {
+      this.emit('error', err);
+    });
+
+    this._socketClient.on('close', () => {
+      this._isConnected = false;
+      this.emit('close');
+    });
+  }
+
+  _assignClientFailureHandlers(...sourceStreams: Readable[]): void {
+    for (const evt of ['close', 'end']) {
+      this._socketClient.once(evt, () => {
+        sourceStreams.map((s) => {
+          s.unpipe(this._socketClient);
+        });
+      });
+    }
+  }
+
+  close(): void {
+    if (!this._socketClient.destroyed) {
+      this._socketClient.end();
+    }
+  }
+}
+
+export { BaseSocketService };

package/src/index.ts

@@ -0,0 +1,34 @@
+import { createLockdownServiceByUDID } from './lib/lockdown/index.js';
+import {
+  PacketStreamClient,
+  PacketStreamServer,
+  TunnelManager,
+} from './lib/tunnel/index.js';
+import {
+  TunnelRegistryServer,
+  startTunnelRegistryServer,
+} from './lib/tunnel/tunnel-registry-server.js';
+import { Usbmux, createUsbmux } from './lib/usbmux/index.js';
+import * as Services from './services.js';
+import { startCoreDeviceProxy } from './services/ios/tunnel-service/index.js';
+
+export type {
+  DiagnosticsService,
+  SyslogService,
+  SocketInfo,
+  TunnelResult,
+  TunnelRegistry,
+  TunnelRegistryEntry,
+} from './lib/types.js';
+export {
+  createUsbmux,
+  Services,
+  Usbmux,
+  TunnelManager,
+  PacketStreamServer,
+  PacketStreamClient,
+  createLockdownServiceByUDID,
+  startCoreDeviceProxy,
+  TunnelRegistryServer,
+  startTunnelRegistryServer,
+};

package/src/lib/apple-tv/constants.ts

@@ -0,0 +1,83 @@
+// Default configuration values for Apple TV pairing behavior
+export const DEFAULT_PAIRING_CONFIG = {
+  timeout: 30000,
+  discoveryTimeout: 5000,
+  maxRetries: 3,
+  pairingDirectory: '.pairing',
+} as const;
+
+// TLV8 component type identifiers used in pairing data exchange
+export const PairingDataComponentType = {
+  METHOD: 0x00,
+  IDENTIFIER: 0x01,
+  SALT: 0x02,
+  PUBLIC_KEY: 0x03,
+  PROOF: 0x04,
+  ENCRYPTED_DATA: 0x05,
+  STATE: 0x06,
+  ERROR: 0x07,
+  RETRY_DELAY: 0x08,
+  CERTIFICATE: 0x09,
+  SIGNATURE: 0x0a,
+  PERMISSIONS: 0x0b,
+  FRAGMENT_DATA: 0x0c,
+  FRAGMENT_LAST: 0x0d,
+  SESSION_ID: 0x0e,
+  TTL: 0x0f,
+  EXTRA_DATA: 0x10,
+  INFO: 0x11,
+  ACL: 0x12,
+  FLAGS: 0x13,
+  VALIDATION_DATA: 0x14,
+  MFI_AUTH_TOKEN: 0x15,
+  MFI_PRODUCT_TYPE: 0x16,
+  SERIAL_NUMBER: 0x17,
+  MFI_AUTH_TOKEN_UUID: 0x18,
+  APP_FLAGS: 0x19,
+  OWNERSHIP_PROOF: 0x1a,
+  SETUP_CODE_TYPE: 0x1b,
+  PRODUCTION_DATA: 0x1c,
+  APP_INFO: 0x1d,
+  SEPARATOR: 0xff,
+} as const;
+
+// Maximum allowed size of a TLV8 fragment
+export const TLV8_MAX_FRAGMENT_SIZE = 255;
+
+// RFC 5054 3072-bit safe prime used for SRP key exchange
+export const SRP_PRIME_3072 = BigInt(
+  '0x' +
+    'FFFFFFFFFFFFFFFFC90FDAA22168C234C4C6628B80DC1CD129024E088A67CC74' +
+    '020BBEA63B139B22514A08798E3404DDEF9519B3CD3A431B302B0A6DF25F1437' +
+    '4FE1356D6D51C245E485B576625E7EC6F44C42E9A637ED6B0BFF5CB6F406B7ED' +
+    'EE386BFB5A899FA5AE9F24117C4B1FE649286651ECE45B3DC2007CB8A163BF05' +
+    '98DA48361C55D39A69163FA8FD24CF5F83655D23DCA3AD961C62F356208552BB' +
+    '9ED529077096966D670C354E4ABC9804F1746C08CA18217C32905E462E36CE3B' +
+    'E39E772C180E86039B2783A2EC07A28FB5C55DF06F4C52C9DE2BCBF695581718' +
+    '3995497CEA956AE515D2261898FA051015728E5A8AAAC42DAD33170D04507A33' +
+    'A85521ABDF1CBA64ECFB850458DBEF0A8AEA71575D060C7DB3970F85A6E1E4C7' +
+    'ABF5AE8CDB0933D71E8C94E04A25619DCEE3D2261AD2EE6BF12FFA06D98A0864' +
+    'D87602733EC86A64521F2B18177B200CBBE117577A615D6C770988C0BAD946E2' +
+    '08E24FA074E5AB3143DB5BFCE0FD108E4B82D120A93AD2CAFFFFFFFFFFFFFFFF',
+);
+
+// Generator value (g=5) used in SRP key exchange
+export const SRP_GENERATOR = BigInt(5);
+
+// Hash algorithm used in SRP protocol (per HomeKit spec)
+export const SRP_HASH_ALGORITHM = 'sha512';
+
+// SRP username identifier used in Apple Pair-Setup
+export const SRP_USERNAME = 'Pair-Setup';
+
+// Key length in bytes for SRP (3072 bits = 384 bytes)
+export const SRP_KEY_LENGTH_BYTES = 384;
+
+// Number of bits for SRP private key (usually 256 bits)
+export const SRP_PRIVATE_KEY_BITS = 256;
+
+// Hash algorithm used for HKDF in pairing encryption
+export const HKDF_HASH_ALGORITHM = 'sha512';
+
+// Output length (in bytes) for HKDF key derivation
+export const HKDF_HASH_LENGTH = 64;

package/src/lib/apple-tv/errors.ts

@@ -0,0 +1,31 @@
+// Base error class for all Apple TV related errors
+export class AppleTVError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = new.target.name;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
+// Represents an error that occurs during the pairing process
+export class PairingError extends AppleTVError {
+  constructor(
+    message: string,
+    public code?: string,
+    public details?: any,
+  ) {
+    super(message);
+  }
+}
+
+// Represents an error related to network communication
+export class NetworkError extends AppleTVError {}
+
+// Represents an error occurring during cryptographic operations
+export class CryptographyError extends AppleTVError {}
+
+// Represents an error specific to SRP (Secure Remote Password) protocol
+export class SRPError extends AppleTVError {}
+
+// Represents an error related to TLV8 encoding/decoding
+export class TLV8Error extends AppleTVError {}

package/src/lib/apple-tv/tlv/decoder.ts

@@ -0,0 +1,68 @@
+import { TLV8Error } from '../errors.js';
+import type { PairingDataComponentTypeValue, TLV8Item } from '../types.js';
+
+/**
+ * Decodes a TLV8-formatted buffer into an array of TLV8 items.
+ *
+ * @param buffer - A Node.js Buffer containing TLV8 encoded data
+ * @returns Array of TLV8Item objects with `type` and `data`
+ * @throws TLV8Error if the buffer does not contain valid TLV8 data
+ */
+export function decodeTLV8(buffer: Buffer): TLV8Item[] {
+  const items: TLV8Item[] = [];
+  let offset = 0;
+
+  while (offset < buffer.length) {
+    if (offset + 2 > buffer.length) {
+      throw new TLV8Error(
+        `Invalid TLV8: insufficient data for type and length at offset ${offset}`,
+      );
+    }
+
+    const type = buffer[offset] as PairingDataComponentTypeValue;
+    const length = buffer[offset + 1];
+    offset += 2;
+
+    if (offset + length > buffer.length) {
+      throw new TLV8Error(
+        `Invalid TLV8: insufficient data for value at offset ${offset}`,
+      );
+    }
+
+    const data = buffer.subarray(offset, offset + length);
+    offset += length;
+
+    items.push({ type, data });
+  }
+
+  return items;
+}
+
+/**
+ * Decodes a TLV8-formatted buffer into a dictionary mapping
+ * each TLV8 type to its corresponding data buffer. If the same
+ * type occurs more than once, their values are concatenated.
+ *
+ * @param buffer - A Node.js Buffer containing TLV8 encoded data
+ * @returns A dictionary of type-value mappings
+ */
+export function decodeTLV8ToDict(
+  buffer: Buffer,
+): Partial<Record<PairingDataComponentTypeValue, Buffer>> {
+  const items = decodeTLV8(buffer);
+  const result: Partial<Record<PairingDataComponentTypeValue, Buffer[]>> = {};
+
+  for (const { type, data } of items) {
+    if (!result[type]) {
+      result[type] = [];
+    }
+    result[type]!.push(data);
+  }
+
+  return Object.fromEntries(
+    Object.entries(result).map(([type, buffers]) => [
+      type,
+      Buffer.concat(buffers as Buffer[]),
+    ]),
+  ) as Partial<Record<PairingDataComponentTypeValue, Buffer>>;
+}

package/src/lib/apple-tv/tlv/encoder.ts

@@ -0,0 +1,33 @@
+import { TLV8_MAX_FRAGMENT_SIZE } from '../constants.js';
+import type { TLV8Item } from '../types.js';
+
+/**
+ * Encodes an array of TLV8 items into a single TLV8-compliant buffer.
+ * If a data value exceeds TLV8_MAX_FRAGMENT_SIZE, it will be split across multiple entries.
+ *
+ * @param items - Array of TLV8 items to encode
+ * @returns A Buffer containing the encoded TLV8 data
+ */
+export function encodeTLV8(items: TLV8Item[]): Buffer {
+  const chunks: Buffer[] = [];
+
+  for (const { type, data } of items) {
+    let offset = 0;
+
+    while (offset < data.length) {
+      const fragmentLength = Math.min(
+        TLV8_MAX_FRAGMENT_SIZE,
+        data.length - offset,
+      );
+
+      chunks.push(
+        Buffer.from([type, fragmentLength]),
+        data.subarray(offset, offset + fragmentLength),
+      );
+
+      offset += fragmentLength;
+    }
+  }
+
+  return Buffer.concat(chunks);
+}

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

@@ -0,0 +1,6 @@
+export { encodeTLV8 } from './encoder.js';
+export { decodeTLV8, decodeTLV8ToDict } from './decoder.js';
+export {
+  createSetupManualPairingData,
+  createPairVerificationData,
+} from './pairing-tlv.js';

package/src/lib/apple-tv/tlv/pairing-tlv.ts

@@ -0,0 +1,31 @@
+import { PairingDataComponentType } from '../constants.js';
+import { encodeTLV8 } from './encoder.js';
+
+/**
+ * Creates TLV8-encoded setup data for manual pairing, with default METHOD and STATE.
+ *
+ * @returns Base64-encoded TLV8 string for manual pairing
+ */
+export function createSetupManualPairingData(): string {
+  const tlv = encodeTLV8([
+    { type: PairingDataComponentType.METHOD, data: Buffer.from([0x00]) },
+    { type: PairingDataComponentType.STATE, data: Buffer.from([0x01]) },
+  ]);
+
+  return tlv.toString('base64');
+}
+
+/**
+ * Creates TLV8-encoded data for pair verification, including the X25519 public key.
+ *
+ * @param x25519PublicKey - A buffer containing the X25519 public key
+ * @returns Base64-encoded TLV8 string for verification
+ */
+export function createPairVerificationData(x25519PublicKey: Buffer): string {
+  const tlv = encodeTLV8([
+    { type: PairingDataComponentType.STATE, data: Buffer.from([0x01]) },
+    { type: PairingDataComponentType.PUBLIC_KEY, data: x25519PublicKey },
+  ]);
+
+  return tlv.toString('base64');
+}

package/src/lib/apple-tv/types.ts

@@ -0,0 +1,58 @@
+// Represents detailed information about an Apple TV device
+export interface AppleTVDeviceInfo {
+  altIRK: Buffer;
+  btAddr: string;
+  mac: Buffer;
+  remotePairingSerialNumber: string;
+  accountID: string;
+  model: string;
+  name: string;
+}
+
+// Represents a key pair used during pairing (public/private keys)
+export interface PairingKeys {
+  publicKey: Buffer;
+  privateKey: Buffer;
+}
+
+// Represents the result of a pairing attempt
+export interface PairingResult {
+  success: boolean;
+  pairingFile?: string;
+  deviceId: string;
+  error?: Error;
+}
+
+// Configuration options for the pairing process
+export interface PairingConfig {
+  timeout: number;
+  discoveryTimeout: number;
+  maxRetries: number;
+  pairingDirectory: string;
+}
+
+// Represents a TLV8 data item with a type and binary data
+export interface TLV8Item {
+  type: PairingDataComponentTypeValue;
+  data: Buffer;
+}
+
+// Type alias for TLV8 component type values
+export type PairingDataComponentTypeValue = number;
+
+// Represents any valid Opack2 data type
+export type Opack2Value =
+  | null
+  | undefined
+  | boolean
+  | number
+  | string
+  | Buffer
+  | Opack2Array
+  | Opack2Dictionary;
+
+// Represents an array of Opack2 values
+export interface Opack2Array extends Array<Opack2Value> {}
+
+// Represents a dictionary of Opack2 values
+export interface Opack2Dictionary extends Record<string, Opack2Value> {}

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

@@ -0,0 +1,90 @@
+/**
+ * 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: bigint, length: number): Buffer {
+  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: Buffer): bigint {
+  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: bigint): Buffer {
+  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: bigint,
+  exponent: bigint,
+  modulus: bigint,
+): bigint {
+  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/src/lib/apple-tv/utils/index.ts

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

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

@@ -0,0 +1,43 @@
+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: string): string {
+  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;
+}