@bharper/atv-js 0.2.3

package/src/crypto/chacha20.ts

@@ -0,0 +1,93 @@
+/**
+ * ChaCha20-Poly1305 AEAD encryption with counter-based nonces.
+ * Uses @noble/ciphers for pure JS implementation (works in Electron).
+ */
+
+import { chacha20poly1305 } from '@noble/ciphers/chacha.js';
+
+const NONCE_LENGTH = 12;
+const AUTH_TAG_LENGTH = 16;
+
+export { AUTH_TAG_LENGTH };
+
+export class Chacha20Cipher {
+  private outKey: Buffer;
+  private inKey: Buffer;
+  private outCounter = 0;
+  private inCounter = 0;
+  private nonceLength: number;
+
+  constructor(outKey: Buffer, inKey: Buffer, nonceLength = 12) {
+    this.outKey = outKey;
+    this.inKey = inKey;
+    this.nonceLength = nonceLength;
+  }
+
+  private padNonce(nonce: Buffer): Buffer {
+    if (nonce.length >= NONCE_LENGTH) return nonce;
+    const padded = Buffer.alloc(NONCE_LENGTH);
+    nonce.copy(padded, NONCE_LENGTH - nonce.length);
+    return padded;
+  }
+
+  private getOutNonce(): Buffer {
+    const nonce = Buffer.alloc(this.nonceLength);
+    writeLECounter(nonce, this.outCounter, this.nonceLength);
+    return this.nonceLength !== NONCE_LENGTH ? this.padNonce(nonce) : nonce;
+  }
+
+  private getInNonce(): Buffer {
+    const nonce = Buffer.alloc(this.nonceLength);
+    writeLECounter(nonce, this.inCounter, this.nonceLength);
+    return this.nonceLength !== NONCE_LENGTH ? this.padNonce(nonce) : nonce;
+  }
+
+  encrypt(data: Buffer, nonce?: Buffer, aad?: Buffer): Buffer {
+    let useNonce: Buffer;
+    if (nonce === undefined) {
+      useNonce = this.getOutNonce();
+      this.outCounter++;
+    } else {
+      useNonce = nonce.length < NONCE_LENGTH ? this.padNonce(nonce) : nonce;
+    }
+
+    // Use @noble/ciphers chacha20-poly1305 (pure JS, works in Electron)
+    const cipher = chacha20poly1305(this.outKey, useNonce, aad);
+    const encrypted = cipher.encrypt(data);
+    return Buffer.from(encrypted);
+  }
+
+  decrypt(data: Buffer, nonce?: Buffer, aad?: Buffer): Buffer {
+    let useNonce: Buffer;
+    if (nonce === undefined) {
+      useNonce = this.getInNonce();
+      this.inCounter++;
+    } else {
+      useNonce = nonce.length < NONCE_LENGTH ? this.padNonce(nonce) : nonce;
+    }
+
+    // Use @noble/ciphers chacha20-poly1305 (pure JS, works in Electron)
+    const decipher = chacha20poly1305(this.inKey, useNonce, aad);
+    const decrypted = decipher.decrypt(data);
+    return Buffer.from(decrypted);
+  }
+}
+
+/**
+ * 8-byte counter variant: nonce = [4 zero bytes][8-byte LE counter].
+ * Used for pairing steps with explicit nonces like "PS-Msg05", "PV-Msg02".
+ */
+export class Chacha20Cipher8byteNonce extends Chacha20Cipher {
+  constructor(outKey: Buffer, inKey: Buffer) {
+    super(outKey, inKey, 8);
+  }
+}
+
+function writeLECounter(buf: Buffer, counter: number, length: number): void {
+  // Use BigInt to avoid JavaScript's 32-bit limit on bit operations
+  let c = BigInt(counter);
+  for (let i = 0; i < length && i < 8; i++) {
+    buf[i] = Number(c & 0xffn);
+    c >>= 8n;
+  }
+}

package/src/crypto/hkdf.ts

@@ -0,0 +1,18 @@
+/**
+ * HKDF-SHA512 key derivation.
+ * Port of pyatv/auth/hap_srp.py hkdf_expand().
+ */
+
+import * as crypto from 'crypto';
+
+export function hkdfExpand(salt: string, info: string, sharedSecret: Buffer): Buffer {
+  return Buffer.from(
+    crypto.hkdfSync(
+      'sha512',
+      sharedSecret,
+      Buffer.from(salt, 'utf-8'),
+      Buffer.from(info, 'utf-8'),
+      32
+    )
+  );
+}

package/src/index.ts

@@ -0,0 +1,248 @@
+/**
+ * atv-js: Apple TV control library.
+ * mDNS discovery, AirPlay/Companion pairing, remote control, keyboard input.
+ */
+
+export { AppleTVDevice, scan } from './mdns';
+export { HapCredentials, Credentials, parseCredentials, serializeCredentials } from './pairing/credentials';
+export { RemoteKey, HidCommand, MediaControlCommand } from './companion/remote';
+export { KeyboardFocusState } from './companion/keyboard';
+
+import { AppleTVDevice } from './mdns';
+import { CompanionConnection } from './companion/connection';
+import { CompanionProtocol } from './companion/protocol';
+import { CompanionPairSetupProcedure } from './companion/auth';
+import {
+  getCompanionPairingConnection,
+  releaseCompanionPairingConnection,
+} from './companion/pairing_keepalive';
+import { SRPAuthHandler } from './pairing/srp';
+import { HapCredentials, Credentials, serializeCredentials, parseCredentials } from './pairing/credentials';
+import {
+  AirPlayPairingSession,
+  startAirPlayPairing as _startAirPlayPairing,
+  finishAirPlayPairing as _finishAirPlayPairing,
+} from './airplay/auth';
+import { sendKeyPress, sendKeyDown, sendKeyUp, RemoteKey } from './companion/remote';
+import {
+  getText as _getText,
+  setText as _setText,
+  getKeyboardFocus as _getKeyboardFocus,
+  watchKeyboardFocus as _watchKeyboardFocus,
+  KeyboardFocusState,
+} from './companion/keyboard';
+import { FrameType } from './companion/connection';
+import { opackFloat } from './opack';
+
+// ---- Pairing Sessions ----
+
+export interface PairingSession {
+  /** @internal */
+  _type: 'airplay' | 'companion';
+  /** @internal */
+  _airplay?: AirPlayPairingSession;
+  /** @internal */
+  _companionProtocol?: CompanionProtocol;
+  /** @internal */
+  _companionProcedure?: CompanionPairSetupProcedure;
+}
+
+/**
+ * Start AirPlay pairing with a discovered device.
+ * This triggers the PIN display on the Apple TV.
+ */
+export async function startAirPlayPairing(device: AppleTVDevice): Promise<PairingSession> {
+  const session = await _startAirPlayPairing(device.address, device.airplayPort);
+  return { _type: 'airplay', _airplay: session };
+}
+
+/**
+ * Finish AirPlay pairing with the PIN shown on screen.
+ */
+export async function finishAirPlayPairing(
+  session: PairingSession,
+  pin: string,
+  displayName?: string,
+): Promise<HapCredentials> {
+  if (session._type !== 'airplay' || !session._airplay) {
+    throw new Error('Not an AirPlay pairing session');
+  }
+  return _finishAirPlayPairing(session._airplay, pin, displayName);
+}
+
+/**
+ * Start Companion protocol pairing with a discovered device.
+ * This triggers a second PIN display on the Apple TV.
+ */
+export async function startCompanionPairing(device: AppleTVDevice): Promise<PairingSession> {
+  const connection = getCompanionPairingConnection(device.address, device.port);
+  const protocol = new CompanionProtocol(connection, null);
+  connection.setListener(protocol);
+  const srp = new SRPAuthHandler();
+  const procedure = new CompanionPairSetupProcedure(protocol, srp);
+
+  // Start pairing (connects + sends PS_Start)
+  await procedure.startPairing();
+
+  return {
+    _type: 'companion',
+    _companionProtocol: protocol,
+    _companionProcedure: procedure,
+  };
+}
+
+/**
+ * Finish Companion pairing with the PIN shown on screen.
+ */
+export async function finishCompanionPairing(
+  session: PairingSession,
+  pin: string,
+  displayName?: string,
+): Promise<HapCredentials> {
+  if (session._type !== 'companion' || !session._companionProcedure) {
+    throw new Error('Not a Companion pairing session');
+  }
+  const creds = await session._companionProcedure.finishPairing(pin.trim(), displayName);
+
+  // Release the pairing connection back to the keep-alive cache
+  if (session._companionProtocol) {
+    releaseCompanionPairingConnection(session._companionProtocol.connection);
+  }
+
+  return creds;
+}
+
+// ---- Connection ----
+
+export interface AppleTVConnection {
+  protocol: CompanionProtocol;
+  device: AppleTVDevice;
+  credentials: Credentials;
+  /** @internal */
+  _keyboardFocusState: KeyboardFocusState;
+}
+
+/**
+ * Connect to an Apple TV using stored credentials.
+ * Performs pair-verify and sets up encrypted Companion channel.
+ */
+export async function connect(
+  device: AppleTVDevice,
+  credentials: Credentials,
+): Promise<AppleTVConnection> {
+  const connection = new CompanionConnection(device.address, device.port);
+  const protocol = new CompanionProtocol(connection, credentials.companion);
+  connection.setListener(protocol);
+
+  // Connect, verify credentials, enable encryption
+  await protocol.start();
+
+  // Post-connection initialization (order matters!)
+  // 1. Send system info
+  // Client ID is stored hex-encoded in credentials, decode to get the actual UUID bytes
+  const clientIdHex = credentials.companion.split(':')[3] || '';
+  const clientIdBytes = Buffer.from(clientIdHex, 'hex');  // UUID as bytes
+  await protocol.sendCommand('_systemInfo', {
+    _bf: 0,
+    _cf: 512,
+    _clFl: 128,
+    _i: null,
+    _idsID: clientIdBytes,
+    _pubID: 'FF:70:79:61:74:76',
+    _sf: 256,
+    _sv: '170.18',
+    model: 'iPhone10,6',
+    name: 'atv-js',
+  });
+
+  // 2. Start touch input (must be before _sessionStart)
+  await protocol.sendCommand('_touchStart', {
+    _height: opackFloat(1000.0),
+    _tFl: 0,
+    _width: opackFloat(1000.0),
+  });
+
+  // 3. Start a session
+  const sessionId = Math.floor(Math.random() * 0xFFFFFFFF);
+  await protocol.sendCommand('_sessionStart', {
+    _srvT: 'com.apple.tvremoteservices',
+    _sid: sessionId,
+  });
+
+  // 4. Start text input session
+  await protocol.sendCommand('_tiStart', {});
+
+  // 5. Subscribe to media control events
+  protocol.subscribeEvent('_iMC');
+
+  const conn: AppleTVConnection = {
+    protocol,
+    device,
+    credentials,
+    _keyboardFocusState: KeyboardFocusState.Unknown,
+  };
+
+  // Watch keyboard focus state
+  _watchKeyboardFocus(protocol, (state) => {
+    conn._keyboardFocusState = state;
+  });
+
+  return conn;
+}
+
+// ---- Remote Control ----
+
+/**
+ * Send a remote control key press (button down + up).
+ */
+export async function sendKey(conn: AppleTVConnection, key: RemoteKey | string): Promise<void> {
+  return sendKeyPress(conn.protocol, key);
+}
+
+export { sendKeyDown, sendKeyUp };
+
+// ---- Keyboard ----
+
+/**
+ * Check if keyboard is currently focused.
+ */
+export async function getKeyboardFocusState(conn: AppleTVConnection): Promise<boolean> {
+  return _getKeyboardFocus(conn.protocol);
+}
+
+/**
+ * Get the current text from a focused keyboard field.
+ */
+export async function getText(conn: AppleTVConnection): Promise<string | null> {
+  return _getText(conn.protocol);
+}
+
+/**
+ * Set (replace) the text in a focused keyboard field.
+ */
+export async function setText(conn: AppleTVConnection, text: string): Promise<void> {
+  return _setText(conn.protocol, text);
+}
+
+// ---- Connection Management ----
+
+/**
+ * Set a handler for connection loss events.
+ */
+export function onConnectionLost(conn: AppleTVConnection, handler: (error?: Error) => void): void {
+  conn.protocol.onConnectionLost = handler;
+}
+
+/**
+ * Disconnect from the Apple TV.
+ */
+export function disconnect(conn: AppleTVConnection): void {
+  conn.protocol.close();
+}
+
+/**
+ * Check if still connected to the Apple TV.
+ */
+export function isConnected(conn: AppleTVConnection): boolean {
+  return conn.protocol.connection.isConnected;
+}

package/src/mdns.ts

@@ -0,0 +1,198 @@
+/**
+ * mDNS device scanning for Apple TV discovery.
+ * Queries for _companion-link._tcp and _airplay._tcp services.
+ */
+
+import mdns from 'multicast-dns';
+
+export interface AppleTVDevice {
+  name: string;
+  address: string;
+  /** Companion protocol port */
+  port: number;
+  /** AirPlay port */
+  airplayPort: number;
+  /** Unique device identifier (from mDNS name or properties) */
+  identifier: string;
+  /** Device model (e.g. "AppleTV6,2") */
+  model: string;
+  /** Raw mDNS TXT properties */
+  properties: Record<string, string>;
+}
+
+interface DiscoveredService {
+  name: string;
+  address: string;
+  port: number;
+  properties: Record<string, string>;
+}
+
+const APPLE_TV_MODELS = new Set([
+  'J33AP',
+  'J33DAP',
+  'J42dAP',
+  'J105aAP',
+  'J305AP',
+  'J255AP',
+]);
+
+function isAppleTvModel(model: string): boolean {
+  if (!model) return false;
+  if (model.startsWith('J')) return true;
+  return APPLE_TV_MODELS.has(model);
+}
+
+export async function scan(timeout = 5000, onlyAppleTV = true): Promise<AppleTVDevice[]> {
+  return new Promise((resolve) => {
+    const browser = mdns();
+    const companionServices = new Map<string, DiscoveredService>();
+    const airplayServices = new Map<string, DiscoveredService>();
+    const deviceInfoModels = new Map<string, string>(); // device name → model from _device-info
+    const addressMap = new Map<string, string>();
+
+    browser.on('response', (response: any) => {
+      // Collect A/AAAA records for hostname→IP resolution
+      for (const answer of [...(response.answers || []), ...(response.additionals || [])]) {
+        if (answer.type === 'A') {
+          addressMap.set(answer.name, answer.data);
+        }
+      }
+
+      // Process all records (answers + additionals)
+      const allRecords = [...(response.answers || []), ...(response.additionals || [])];
+
+      for (const answer of allRecords) {
+        if (answer.type === 'SRV') {
+          const name = answer.name;
+          const isCompanion = name.endsWith('._companion-link._tcp.local');
+          const isAirplay = name.endsWith('._airplay._tcp.local');
+
+          if (isCompanion || isAirplay) {
+            const deviceName = name.split('.')[0];
+            const target = answer.data?.target;
+            const port = answer.data?.port;
+            const ip = addressMap.get(target) || '';
+
+            const svc: DiscoveredService = {
+              name: deviceName,
+              address: ip,
+              port,
+              properties: {},
+            };
+
+            if (isCompanion) {
+              companionServices.set(deviceName, svc);
+            } else {
+              airplayServices.set(deviceName, svc);
+            }
+          }
+        }
+
+        if (answer.type === 'TXT') {
+          const name = answer.name;
+          const isCompanion = name.endsWith('._companion-link._tcp.local');
+          const isAirplay = name.endsWith('._airplay._tcp.local');
+          const isDeviceInfo = name.endsWith('._device-info._tcp.local');
+          const deviceName = name.split('.')[0];
+
+          const props: Record<string, string> = {};
+          if (Array.isArray(answer.data)) {
+            for (const entry of answer.data) {
+              const str = entry instanceof Buffer ? entry.toString('utf-8') : String(entry);
+              const eqIdx = str.indexOf('=');
+              if (eqIdx >= 0) {
+                props[str.substring(0, eqIdx)] = str.substring(eqIdx + 1);
+              }
+            }
+          }
+
+          if (isCompanion) {
+            const existing = companionServices.get(deviceName);
+            if (existing) existing.properties = { ...existing.properties, ...props };
+          } else if (isAirplay) {
+            const existing = airplayServices.get(deviceName);
+            if (existing) existing.properties = { ...existing.properties, ...props };
+          } else if (isDeviceInfo && props['model']) {
+            // _device-info._tcp.local contains the actual device model
+            deviceInfoModels.set(deviceName, props['model']);
+          }
+        }
+      }
+
+      // Also resolve addresses found in SRV targets
+      for (const svc of [...companionServices.values(), ...airplayServices.values()]) {
+        if (!svc.address) {
+          for (const answer of allRecords) {
+            if (answer.type === 'A') {
+              addressMap.set(answer.name, answer.data);
+            }
+          }
+        }
+      }
+    });
+
+    // Send queries for companion, airplay, and device-info services
+    const queryServices = () => {
+      browser.query([
+        { name: '_companion-link._tcp.local', type: 'PTR' },
+        { name: '_airplay._tcp.local', type: 'PTR' },
+        { name: '_device-info._tcp.local', type: 'PTR' },
+      ]);
+    };
+
+    // Send initial query
+    queryServices();
+
+    // Send a second query midway for better discovery
+    setTimeout(queryServices, timeout / 2);
+
+    setTimeout(() => {
+      browser.destroy();
+
+      // Merge companion and airplay services by device name
+      const devices: AppleTVDevice[] = [];
+      const allNames = new Set([...companionServices.keys(), ...airplayServices.keys()]);
+
+      for (const name of allNames) {
+        const companion = companionServices.get(name);
+        const airplay = airplayServices.get(name);
+
+        // Need at least companion service for remote control
+        if (!companion) continue;
+
+        // Resolve address from either service or address map
+        let address = companion.address || airplay?.address || '';
+        if (!address) {
+          // Try to find address from addressMap
+          for (const [hostname, ip] of addressMap) {
+            if (hostname.includes(name.replace(/ /g, '-'))) {
+              address = ip;
+              break;
+            }
+          }
+        }
+
+        if (!address) continue;
+
+        const allProps = { ...companion.properties, ...airplay?.properties };
+
+        // Model comes from _device-info._tcp.local service, not companion/airplay
+        const model = deviceInfoModels.get(name) || allProps['model'] || allProps['rpmd'] || '';
+
+        if (onlyAppleTV && !isAppleTvModel(model)) continue;
+
+        devices.push({
+          name,
+          address,
+          port: companion.port,
+          airplayPort: airplay?.port || 7000,
+          identifier: allProps['deviceid'] || allProps['MACAddress'] || name,
+          model,
+          properties: allProps,
+        });
+      }
+
+      resolve(devices);
+    }, timeout);
+  });
+}