appium-ios-remotexpc 0.0.4 → 0.0.5

package/build/src/lib/apple-tv/encryption/opack2.js

@@ -0,0 +1,203 @@
+import * as constants from '../constants.js';
+import { AppleTVError } from '../errors.js';
+/**
+ * OPACK2 binary serialization format encoder
+ * Implements Apple's OPACK2 protocol for efficient binary serialization of structured data
+ */
+export class Opack2 {
+    /**
+     * Serializes a JavaScript object to OPACK2 binary format
+     * @param obj - The object to serialize (supports primitives, arrays, objects, and Buffers)
+     * @returns Buffer containing the serialized data
+     * @throws AppleTVError if the object contains unsupported types
+     */
+    static dumps(obj) {
+        return this.encode(obj);
+    }
+    /**
+     * Main encoding dispatcher that routes values to appropriate type-specific encoders
+     * @param obj - Value to encode
+     * @returns Buffer containing encoded value
+     * @throws AppleTVError for unsupported types
+     */
+    static encode(obj) {
+        if (obj === null || obj === undefined) {
+            return Buffer.from([constants.OPACK2_NULL]);
+        }
+        if (typeof obj === 'boolean') {
+            return Buffer.from([
+                obj ? constants.OPACK2_TRUE : constants.OPACK2_FALSE,
+            ]);
+        }
+        if (typeof obj === 'number') {
+            return this.encodeNumber(obj);
+        }
+        if (typeof obj === 'string') {
+            return this.encodeString(obj);
+        }
+        if (Buffer.isBuffer(obj)) {
+            return this.encodeBytes(obj);
+        }
+        if (Array.isArray(obj)) {
+            return this.encodeArray(obj);
+        }
+        if (typeof obj === 'object' &&
+            !Array.isArray(obj) &&
+            !Buffer.isBuffer(obj)) {
+            return this.encodeDict(obj);
+        }
+        throw new AppleTVError(`Unsupported type for OPACK2 serialization: ${typeof obj}`);
+    }
+    /**
+     * Encodes numeric values with the appropriate size optimization
+     * @param num - Number to encode
+     * @returns Buffer containing encoded number
+     */
+    static encodeNumber(num) {
+        if (!Number.isInteger(num) || num < 0) {
+            const buffer = Buffer.allocUnsafe(5);
+            buffer[0] = constants.OPACK2_FLOAT_MARKER;
+            buffer.writeFloatLE(num, 1);
+            return buffer;
+        }
+        if (num <= constants.OPACK2_SMALL_INT_MAX) {
+            return Buffer.from([num + constants.OPACK2_SMALL_INT_OFFSET]);
+        }
+        if (num <= constants.OPACK2_UINT8_MAX) {
+            return Buffer.from([constants.OPACK2_INT8_MARKER, num]);
+        }
+        if (num <= constants.OPACK2_UINT32_MAX) {
+            const buffer = Buffer.allocUnsafe(5);
+            buffer[0] = constants.OPACK2_INT32_MARKER;
+            buffer.writeUInt32LE(num, 1);
+            return buffer;
+        }
+        if (num <= Number.MAX_SAFE_INTEGER) {
+            const buffer = Buffer.allocUnsafe(9);
+            buffer[0] = constants.OPACK2_INT64_MARKER;
+            buffer.writeBigUInt64LE(BigInt(num), 1);
+            return buffer;
+        }
+        throw new AppleTVError(`Number too large for OPACK2 encoding: ${num}`);
+    }
+    /**
+     * Encodes UTF-8 strings with length-optimized headers
+     * @param str - String to encode
+     * @returns Buffer containing encoded string
+     */
+    static encodeString(str) {
+        const encoded = Buffer.from(str, 'utf8');
+        const length = encoded.length;
+        if (length <= constants.OPACK2_SMALL_STRING_MAX) {
+            return Buffer.concat([
+                Buffer.from([constants.OPACK2_SMALL_STRING_BASE + length]),
+                encoded,
+            ]);
+        }
+        if (length <= constants.OPACK2_UINT8_MAX) {
+            return Buffer.concat([
+                Buffer.from([constants.OPACK2_STRING_8BIT_LEN_MARKER, length]),
+                encoded,
+            ]);
+        }
+        if (length <= constants.OPACK2_UINT16_MAX) {
+            const header = Buffer.allocUnsafe(3);
+            header[0] = constants.OPACK2_STRING_16BIT_LEN_MARKER;
+            header.writeUInt16BE(length, 1);
+            return Buffer.concat([header, encoded]);
+        }
+        if (length <= constants.OPACK2_UINT32_MAX) {
+            const header = Buffer.allocUnsafe(5);
+            header[0] = constants.OPACK2_STRING_32BIT_LEN_MARKER;
+            header.writeUInt32BE(length, 1);
+            return Buffer.concat([header, encoded]);
+        }
+        throw new AppleTVError(`String too long for OPACK2 encoding: ${length} bytes`);
+    }
+    /**
+     * Encodes binary data with length-optimized headers
+     * @param bytes - Buffer to encode
+     * @returns Buffer containing encoded binary data
+     */
+    static encodeBytes(bytes) {
+        const length = bytes.length;
+        if (length <= constants.OPACK2_SMALL_BYTES_MAX) {
+            return Buffer.concat([
+                Buffer.from([constants.OPACK2_SMALL_BYTES_BASE + length]),
+                bytes,
+            ]);
+        }
+        if (length <= constants.OPACK2_UINT8_MAX) {
+            return Buffer.concat([
+                Buffer.from([constants.OPACK2_BYTES_8BIT_LEN_MARKER, length]),
+                bytes,
+            ]);
+        }
+        if (length <= constants.OPACK2_UINT16_MAX) {
+            const header = Buffer.allocUnsafe(3);
+            header[0] = constants.OPACK2_BYTES_16BIT_LEN_MARKER;
+            header.writeUInt16BE(length, 1);
+            return Buffer.concat([header, bytes]);
+        }
+        if (length <= constants.OPACK2_UINT32_MAX) {
+            const header = Buffer.allocUnsafe(5);
+            header[0] = constants.OPACK2_BYTES_32BIT_LEN_MARKER;
+            header.writeUInt32BE(length, 1);
+            return Buffer.concat([header, bytes]);
+        }
+        throw new AppleTVError(`Byte array too long for OPACK2 encoding: ${length} bytes`);
+    }
+    /**
+     * Encodes arrays with count-optimized headers
+     * @param arr - Array to encode
+     * @returns Buffer containing encoded array
+     */
+    static encodeArray(arr) {
+        const length = arr.length;
+        if (length <= constants.OPACK2_SMALL_ARRAY_MAX) {
+            const parts = [
+                Buffer.from([constants.OPACK2_SMALL_ARRAY_BASE + length]),
+            ];
+            for (const item of arr) {
+                parts.push(this.encode(item));
+            }
+            return Buffer.concat(parts);
+        }
+        const parts = [
+            Buffer.from([constants.OPACK2_VARIABLE_ARRAY_MARKER]),
+        ];
+        for (const item of arr) {
+            parts.push(this.encode(item));
+        }
+        parts.push(Buffer.from([constants.OPACK2_NULL]));
+        return Buffer.concat(parts);
+    }
+    /**
+     * Encodes objects/dictionaries with count-optimized headers
+     * @param dict - Object to encode
+     * @returns Buffer containing encoded dictionary
+     */
+    static encodeDict(dict) {
+        const entries = Object.entries(dict);
+        const length = entries.length;
+        if (length < constants.OPACK2_SMALL_DICT_MAX) {
+            const parts = [
+                Buffer.from([constants.OPACK2_SMALL_DICT_BASE + length]),
+            ];
+            for (const [key, value] of entries) {
+                parts.push(this.encode(key));
+                parts.push(this.encode(value));
+            }
+            return Buffer.concat(parts);
+        }
+        const parts = [
+            Buffer.from([constants.OPACK2_VARIABLE_DICT_MARKER]),
+        ];
+        for (const [key, value] of entries) {
+            parts.push(this.encode(key));
+            parts.push(this.encode(value));
+        }
+        parts.push(Buffer.from([constants.OPACK2_NULL, constants.OPACK2_NULL]));
+        return Buffer.concat(parts);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "appium-ios-remotexpc",
-  "version": "0.0.4",
+  "version": "0.0.5",
   "main": "build/src/index.js",
   "types": "build/src/index.d.ts",
   "type": "module",

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

@@ -81,3 +81,45 @@ export const HKDF_HASH_ALGORITHM = 'sha512';
 
 // Output length (in bytes) for HKDF key derivation
 export const HKDF_HASH_LENGTH = 64;
+
+// OPACK2 encoding constants
+export const OPACK2_NULL = 0x03;
+export const OPACK2_TRUE = 0x01;
+export const OPACK2_FALSE = 0x02;
+export const OPACK2_SMALL_INT_OFFSET = 8;
+export const OPACK2_SMALL_INT_MAX = 0x27;
+export const OPACK2_SMALL_STRING_MAX = 0x20;
+export const OPACK2_SMALL_BYTES_MAX = 0x20;
+export const OPACK2_SMALL_ARRAY_MAX = 15;
+export const OPACK2_SMALL_DICT_MAX = 15;
+
+// OPACK2 number type markers
+export const OPACK2_INT8_MARKER = 0x30;
+export const OPACK2_INT32_MARKER = 0x32;
+export const OPACK2_INT64_MARKER = 0x33;
+export const OPACK2_FLOAT_MARKER = 0x35;
+
+// OPACK2 string type markers
+export const OPACK2_SMALL_STRING_BASE = 0x40;
+export const OPACK2_STRING_8BIT_LEN_MARKER = 0x61;
+export const OPACK2_STRING_16BIT_LEN_MARKER = 0x62;
+export const OPACK2_STRING_32BIT_LEN_MARKER = 0x63;
+
+// OPACK2 bytes type markers
+export const OPACK2_SMALL_BYTES_BASE = 0x70;
+export const OPACK2_BYTES_8BIT_LEN_MARKER = 0x91;
+export const OPACK2_BYTES_16BIT_LEN_MARKER = 0x92;
+export const OPACK2_BYTES_32BIT_LEN_MARKER = 0x93;
+
+// OPACK2 array type markers
+export const OPACK2_SMALL_ARRAY_BASE = 0xd0;
+export const OPACK2_VARIABLE_ARRAY_MARKER = 0xdf;
+
+// OPACK2 dictionary type markers
+export const OPACK2_SMALL_DICT_BASE = 0xe0;
+export const OPACK2_VARIABLE_DICT_MARKER = 0xef;
+
+// OPACK2 size limits
+export const OPACK2_UINT8_MAX = 0xff;
+export const OPACK2_UINT16_MAX = 0xffff;
+export const OPACK2_UINT32_MAX = 0xffffffff;

package/src/lib/apple-tv/encryption/chacha20-poly1305.ts

@@ -0,0 +1,147 @@
+import { logger } from '@appium/support';
+import { createCipheriv, createDecipheriv } from 'node:crypto';
+
+import { CryptographyError } from '../errors.js';
+
+const log = logger.getLogger('ChaCha20Poly1305');
+
+export interface ChaCha20Poly1305Params {
+  plaintext?: Buffer;
+  ciphertext?: Buffer;
+  key: Buffer;
+  nonce: Buffer;
+  aad?: Buffer;
+}
+
+interface DecryptionAttempt {
+  tagLen: number;
+  aad?: Buffer;
+}
+
+/**
+ * Encrypts data using ChaCha20-Poly1305 AEAD cipher
+ * @param params - Encryption parameters including plaintext, key, nonce, and optional AAD
+ * @returns Buffer containing encrypted data concatenated with authentication tag
+ * @throws CryptographyError if encryption fails or required parameters are missing
+ */
+export function encryptChaCha20Poly1305(
+  params: ChaCha20Poly1305Params,
+): Buffer {
+  const { plaintext, key, nonce, aad } = params;
+
+  if (!plaintext) {
+    throw new CryptographyError('Plaintext is required for encryption');
+  }
+
+  if (!key || key.length !== 32) {
+    throw new CryptographyError('Key must be 32 bytes');
+  }
+
+  if (!nonce || nonce.length !== 12) {
+    throw new CryptographyError('Nonce must be 12 bytes');
+  }
+
+  try {
+    const cipher = createCipheriv('chacha20-poly1305', key, nonce) as any;
+
+    if (aad) {
+      cipher.setAAD(aad, { plaintextLength: plaintext.length });
+    }
+
+    const encrypted = Buffer.concat([cipher.update(plaintext), cipher.final()]);
+    const authTag = cipher.getAuthTag();
+
+    return Buffer.concat([encrypted, authTag]);
+  } catch (error) {
+    log.error('ChaCha20-Poly1305 encryption failed:', error);
+    const message = error instanceof Error ? error.message : String(error);
+    throw new CryptographyError(
+      `ChaCha20-Poly1305 encryption failed: ${message}`,
+    );
+  }
+}
+
+/**
+ * Decrypts data using ChaCha20-Poly1305 AEAD cipher with multiple fallback strategies
+ * @param params - Decryption parameters including ciphertext, key, nonce, and optional AAD
+ * @returns Buffer containing decrypted plaintext
+ * @throws CryptographyError if all decryption attempts fail or required parameters are missing
+ */
+export function decryptChaCha20Poly1305(
+  params: ChaCha20Poly1305Params,
+): Buffer {
+  const { ciphertext, key, nonce, aad } = params;
+
+  if (!ciphertext) {
+    throw new CryptographyError('Ciphertext is required for decryption');
+  }
+
+  if (!key || key.length !== 32) {
+    throw new CryptographyError('Key must be 32 bytes');
+  }
+
+  if (!nonce || nonce.length !== 12) {
+    throw new CryptographyError('Nonce must be 12 bytes');
+  }
+
+  if (ciphertext.length < 16) {
+    throw new CryptographyError(
+      'Ciphertext too short to contain authentication tag',
+    );
+  }
+
+  // ChaCha20-Poly1305 in Node.js only supports 16-byte authentication tags
+  const tagLength = 16;
+  const decryptionAttempts: DecryptionAttempt[] = [
+    { tagLen: tagLength, aad },
+    { tagLen: tagLength, aad: Buffer.alloc(0) },
+    { tagLen: tagLength, aad: undefined },
+  ];
+
+  let lastError: Error | undefined;
+
+  for (const attempt of decryptionAttempts) {
+    try {
+      const encrypted = ciphertext.subarray(
+        0,
+        ciphertext.length - attempt.tagLen,
+      );
+      const authTag = ciphertext.subarray(ciphertext.length - attempt.tagLen);
+
+      const decipher = createDecipheriv('chacha20-poly1305', key, nonce) as any;
+      decipher.setAuthTag(authTag);
+
+      if (attempt.aad !== undefined) {
+        decipher.setAAD(attempt.aad, { plaintextLength: encrypted.length });
+      }
+
+      const decrypted = Buffer.concat([
+        decipher.update(encrypted),
+        decipher.final(),
+      ]);
+
+      log.debug(
+        'Decryption successful with AAD:',
+        attempt.aad ? 'provided' : 'none',
+      );
+      return decrypted;
+    } catch (error) {
+      lastError = error instanceof Error ? error : new Error(String(error));
+    }
+  }
+
+  const errorMessage = lastError
+    ? `ChaCha20-Poly1305 decryption failed: ${lastError.message}`
+    : 'ChaCha20-Poly1305 decryption failed: invalid ciphertext or authentication tag';
+
+  // Log the error with stack trace for debugging real failures
+  // Skip logging in test environment to avoid cluttering test output with expected failures
+  if (lastError && process.env.NODE_ENV !== 'test') {
+    log.error('All ChaCha20-Poly1305 decryption attempts failed:', {
+      message: lastError.message,
+      stack: lastError.stack,
+    });
+  }
+
+  throw new CryptographyError(errorMessage);
+}

package/src/lib/apple-tv/encryption/ed25519.ts

@@ -0,0 +1,126 @@
+import { logger } from '@appium/support';
+import {
+  type KeyPairKeyObjectResult,
+  generateKeyPairSync,
+  sign,
+} from 'node:crypto';
+
+import { CryptographyError } from '../errors.js';
+import type { PairingKeys } from '../types.js';
+
+const log = logger.getLogger('Ed25519');
+
+const ED25519_PUBLIC_KEY_LENGTH = 32;
+const ED25519_PRIVATE_KEY_LENGTH = 32;
+const ED25519_PKCS8_PREFIX = Buffer.from(
+  '302e020100300506032b657004220420',
+  'hex',
+);
+
+/**
+ * Generates a new Ed25519 key pair for cryptographic operations
+ * @returns PairingKeys object containing 32-byte public and private key buffers
+ * @throws CryptographyError if key generation fails
+ */
+export function generateEd25519KeyPair(): PairingKeys {
+  try {
+    const keyPair: KeyPairKeyObjectResult = generateKeyPairSync('ed25519');
+
+    const publicKeyDer = keyPair.publicKey.export({
+      type: 'spki',
+      format: 'der',
+    }) as Buffer;
+
+    const privateKeyDer = keyPair.privateKey.export({
+      type: 'pkcs8',
+      format: 'der',
+    }) as Buffer;
+
+    const publicKeyBuffer = extractEd25519PublicKey(publicKeyDer);
+    const privateKeyBuffer = extractEd25519PrivateKey(privateKeyDer);
+
+    return {
+      publicKey: publicKeyBuffer,
+      privateKey: privateKeyBuffer,
+    };
+  } catch (error) {
+    log.error('Failed to generate Ed25519 key pair:', error);
+    const message = error instanceof Error ? error.message : String(error);
+    throw new CryptographyError(
+      `Failed to generate Ed25519 key pair: ${message}`,
+    );
+  }
+}
+
+/**
+ * Creates an Ed25519 digital signature for the provided data
+ * @param data - The data to sign
+ * @param privateKey - 32-byte Ed25519 private key
+ * @returns Buffer containing the 64-byte signature
+ * @throws CryptographyError if signing fails or private key is invalid
+ */
+export function createEd25519Signature(
+  data: Buffer,
+  privateKey: Buffer,
+): Buffer {
+  if (!data || data.length === 0) {
+    throw new CryptographyError('Data to sign cannot be empty');
+  }
+
+  if (!privateKey || privateKey.length !== ED25519_PRIVATE_KEY_LENGTH) {
+    throw new CryptographyError(
+      `Private key must be ${ED25519_PRIVATE_KEY_LENGTH} bytes`,
+    );
+  }
+
+  try {
+    const privateKeyDer = Buffer.concat([ED25519_PKCS8_PREFIX, privateKey]);
+
+    return sign(null, data, {
+      key: privateKeyDer,
+      format: 'der',
+      type: 'pkcs8',
+    });
+  } catch (error) {
+    log.error('Failed to create Ed25519 signature:', error);
+    const message = error instanceof Error ? error.message : String(error);
+    throw new CryptographyError(
+      `Failed to create Ed25519 signature: ${message}`,
+    );
+  }
+}
+
+/**
+ * Extracts the raw 32-byte public key from DER-encoded SPKI format
+ * @param publicKeyDer - DER-encoded public key
+ * @returns 32-byte public key buffer
+ * @throws CryptographyError if extraction fails
+ */
+function extractEd25519PublicKey(publicKeyDer: Buffer): Buffer {
+  if (publicKeyDer.length < ED25519_PUBLIC_KEY_LENGTH) {
+    throw new CryptographyError('Invalid public key DER format');
+  }
+
+  return publicKeyDer.subarray(publicKeyDer.length - ED25519_PUBLIC_KEY_LENGTH);
+}
+
+/**
+ * Extracts the raw 32-byte private key from DER-encoded PKCS#8 format
+ * @param privateKeyDer - DER-encoded private key
+ * @returns 32-byte private key buffer
+ * @throws CryptographyError if extraction fails
+ */
+function extractEd25519PrivateKey(privateKeyDer: Buffer): Buffer {
+  const octetStringPattern = Buffer.from([0x04, 0x20]);
+  const index = privateKeyDer.indexOf(octetStringPattern);
+
+  if (index !== -1 && index + 34 <= privateKeyDer.length) {
+    return privateKeyDer.subarray(index + 2, index + 34);
+  }
+
+  if (privateKeyDer.length >= 48) {
+    return privateKeyDer.subarray(16, 48);
+  }
+
+  throw new CryptographyError('Unable to extract private key from DER format');
+}

package/src/lib/apple-tv/encryption/hkdf.ts

@@ -0,0 +1,95 @@
+import { logger } from '@appium/support';
+import { createHmac } from 'node:crypto';
+
+import { HKDF_HASH_ALGORITHM, HKDF_HASH_LENGTH } from '../constants.js';
+import { CryptographyError } from '../errors.js';
+
+const log = logger.getLogger('HKDF');
+
+export interface HKDFParams {
+  ikm: Buffer;
+  salt: Buffer | null;
+  info: Buffer;
+  length: number;
+}
+
+const MAX_OUTPUT_LENGTH = 255 * HKDF_HASH_LENGTH;
+
+/**
+ * HMAC-based Key Derivation Function (HKDF) as defined in RFC 5869
+ * Derives cryptographic keys from input key material using a two-step process:
+ * 1. Extract: Generate a pseudorandom key from the input key material
+ * 2. Expand: Expand the pseudorandom key to the desired output length
+ *
+ * @param params - HKDF parameters including input key material, salt, info, and desired output length
+ * @returns Buffer containing the derived key material of specified length
+ * @throws CryptographyError if derivation fails or parameters are invalid
+ */
+export function hkdf(params: HKDFParams): Buffer {
+  const { ikm, salt, info, length } = params;
+
+  if (!ikm || ikm.length === 0) {
+    throw new CryptographyError('Input key material (IKM) cannot be empty');
+  }
+
+  if (!info) {
+    throw new CryptographyError('Info parameter is required');
+  }
+
+  if (length <= 0) {
+    throw new CryptographyError('Output length must be positive');
+  }
+
+  if (length > MAX_OUTPUT_LENGTH) {
+    throw new CryptographyError(
+      `Output length cannot exceed ${MAX_OUTPUT_LENGTH} bytes`,
+    );
+  }
+
+  try {
+    const extractedKey = hkdfExtract(ikm, salt);
+    return hkdfExpand(extractedKey, info, length);
+  } catch (error) {
+    log.error('HKDF derivation failed:', error);
+    const message = error instanceof Error ? error.message : String(error);
+    throw new CryptographyError(`HKDF derivation failed: ${message}`);
+  }
+}
+
+/**
+ * HKDF Extract step: generates a pseudorandom key from input key material
+ * @param ikm - Input key material
+ * @param salt - Optional salt value (uses zero salt if null)
+ * @returns Pseudorandom key of hash length
+ */
+function hkdfExtract(ikm: Buffer, salt: Buffer | null): Buffer {
+  const actualSalt = salt || Buffer.alloc(HKDF_HASH_LENGTH);
+  return createHmac(HKDF_HASH_ALGORITHM, actualSalt).update(ikm).digest();
+}
+
+/**
+ * HKDF Expand a step: expands a pseudorandom key to desired output length
+ * @param prk - Pseudorandom key from extract step
+ * @param info - Context and application specific information
+ * @param length - Desired output key material length
+ * @returns Output key material of specified length
+ */
+function hkdfExpand(prk: Buffer, info: Buffer, length: number): Buffer {
+  const numberOfBlocks = Math.ceil(length / HKDF_HASH_LENGTH);
+  const blocks: Buffer[] = [];
+  let previousBlock: Buffer = Buffer.alloc(0);
+
+  for (let blockIndex = 1; blockIndex <= numberOfBlocks; blockIndex++) {
+    const hmac = createHmac(HKDF_HASH_ALGORITHM, prk);
+    hmac.update(previousBlock);
+    hmac.update(info);
+    hmac.update(Buffer.from([blockIndex]));
+
+    const currentBlock = hmac.digest();
+    blocks.push(currentBlock);
+    previousBlock = currentBlock;
+  }
+
+  const outputKeyMaterial = Buffer.concat(blocks);
+  return outputKeyMaterial.subarray(0, length);
+}

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

@@ -0,0 +1,11 @@
+export { Opack2 } from './opack2.js';
+
+export {
+  encryptChaCha20Poly1305,
+  decryptChaCha20Poly1305,
+  type ChaCha20Poly1305Params,
+} from './chacha20-poly1305.js';
+
+export { generateEd25519KeyPair, createEd25519Signature } from './ed25519.js';
+
+export { hkdf, type HKDFParams } from './hkdf.js';