appium-ios-remotexpc 0.0.3 → 0.0.5

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';

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

@@ -0,0 +1,257 @@
+import * as constants from '../constants.js';
+import { AppleTVError } from '../errors.js';
+
+interface SerializableArray extends Array<SerializableValue> {}
+interface SerializableObject extends Record<string, SerializableValue> {}
+
+type SerializableValue =
+  | null
+  | undefined
+  | boolean
+  | number
+  | string
+  | Buffer
+  | SerializableArray
+  | SerializableObject;
+
+/**
+ * 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: SerializableValue): Buffer {
+    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
+   */
+  private static encode(obj: SerializableValue): Buffer {
+    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 as Record<string, SerializableValue>);
+    }
+
+    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
+   */
+  private static encodeNumber(num: number): Buffer {
+    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
+   */
+  private static encodeString(str: string): Buffer {
+    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
+   */
+  private static encodeBytes(bytes: Buffer): Buffer {
+    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
+   */
+  private static encodeArray(arr: SerializableValue[]): Buffer {
+    const length = arr.length;
+
+    if (length <= constants.OPACK2_SMALL_ARRAY_MAX) {
+      const parts: Buffer[] = [
+        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[] = [
+      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
+   */
+  private static encodeDict(dict: Record<string, SerializableValue>): Buffer {
+    const entries = Object.entries(dict);
+    const length = entries.length;
+
+    if (length < constants.OPACK2_SMALL_DICT_MAX) {
+      const parts: Buffer[] = [
+        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[] = [
+      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/.github/dependabot.yml

@@ -1,38 +0,0 @@
-# Dependabot configuration file
-# See: https://docs.github.com/github/administering-a-repository/configuration-options-for-dependency-updates
-
-version: 2
-updates:
-  # Enable npm dependency updates
-  - package-ecosystem: "npm"
-    directory: "/"
-    schedule:
-      interval: "weekly"
-    # Specify which branches to update
-    target-branch: "main"
-    # Set version update strategy
-    versioning-strategy: "auto"
-    # Set review requirements
-    open-pull-requests-limit: 10
-    # Group all dev dependencies together
-    groups:
-      dev-dependencies:
-        patterns:
-          - "*"
-        exclude-patterns:
-          - "@types/*"  # Keep type definitions separate
-    # Labels for pull requests
-    labels:
-      - "dependencies"
-      - "npm"
-
-  # Enable GitHub Actions updates
-  - package-ecosystem: "github-actions"
-    directory: "/"
-    schedule:
-      interval: "monthly"
-    target-branch: "main"
-    # Labels for pull requests
-    labels:
-      - "dependencies"
-      - "github-actions"