@bharper/atv-js 0.2.3

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@bharper/atv-js",
+  "version": "0.2.3",
+  "description": "Apple TV control library - mDNS discovery, AirPlay/Companion pairing, remote control, keyboard input",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bsharper/atvjs.git"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist",
+    "pair": "ts-node examples/pair.ts",
+    "remote": "ts-node examples/remote.ts"
+  },
+  "dependencies": {
+    "@noble/ciphers": "^2.1.1",
+    "bplist-creator": "^0.1.0",
+    "bplist-parser": "^0.3.2",
+    "fast-srp-hap": "^2.0.4",
+    "multicast-dns": "^7.2.5"
+  },
+  "devDependencies": {
+    "@types/multicast-dns": "^7.2.4",
+    "@types/node": "^20.0.0",
+    "ts-node": "^10.9.0",
+    "typescript": "^5.3.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/airplay/auth.ts

@@ -0,0 +1,207 @@
+/**
+ * AirPlay HTTP-based HAP pair-setup and pair-verify.
+ * Port of pyatv/protocols/airplay/auth/hap.py.
+ */
+
+import * as http from 'http';
+import { SRPAuthHandler } from '../pairing/srp';
+import { HapCredentials } from '../pairing/credentials';
+import { TlvValue, readTlv, writeTlv } from '../pairing/tlv';
+
+const AIRPLAY_HEADERS: Record<string, string> = {
+  'User-Agent': 'AirPlay/320.20',
+  'Connection': 'keep-alive',
+  'X-Apple-HKP': '3',
+  'Content-Type': 'application/octet-stream',
+};
+
+async function httpPost(
+  host: string,
+  port: number,
+  path: string,
+  body?: Buffer,
+  agent?: http.Agent,
+): Promise<Buffer> {
+  return new Promise((resolve, reject) => {
+    const headers: Record<string, string | number> = { ...AIRPLAY_HEADERS };
+    if (body) {
+      headers['Content-Length'] = body.length;
+    }
+
+    const req = http.request({ hostname: host, port, path, method: 'POST', headers, agent }, (res) => {
+      const chunks: Buffer[] = [];
+      res.on('data', (chunk: Buffer) => chunks.push(chunk));
+      res.on('end', () => resolve(Buffer.concat(chunks)));
+    });
+    req.on('error', reject);
+    if (body) req.write(body);
+    req.end();
+  });
+}
+
+export interface AirPlayPairingSession {
+  srp: SRPAuthHandler;
+  host: string;
+  port: number;
+  atvSalt: Buffer;
+  atvPubKey: Buffer;
+}
+
+const AIRPLAY_AGENT_IDLE_MS = 2 * 60 * 1000;
+
+type AgentEntry = {
+  agent: http.Agent;
+  lastUsed: number;
+  timer: NodeJS.Timeout;
+};
+
+const agentCache = new Map<string, AgentEntry>();
+
+function agentKey(host: string, port: number): string {
+  return `${host}:${port}`;
+}
+
+function touchAgent(entry: AgentEntry): void {
+  entry.lastUsed = Date.now();
+  if (entry.timer) clearTimeout(entry.timer);
+  entry.timer = setTimeout(() => {
+    if (Date.now() - entry.lastUsed >= AIRPLAY_AGENT_IDLE_MS) {
+      entry.agent.destroy();
+      // Find and remove by identity
+      for (const [key, value] of agentCache) {
+        if (value === entry) {
+          agentCache.delete(key);
+          break;
+        }
+      }
+    }
+  }, AIRPLAY_AGENT_IDLE_MS);
+  if (typeof entry.timer.unref === 'function') entry.timer.unref();
+}
+
+function getPairingAgent(host: string, port: number): http.Agent {
+  const key = agentKey(host, port);
+  const existing = agentCache.get(key);
+  if (existing) {
+    touchAgent(existing);
+    return existing.agent;
+  }
+
+  const agent = new http.Agent({ keepAlive: true, maxSockets: 1, maxFreeSockets: 1 });
+  agent.on('free', (socket) => {
+    socket.unref();
+  });
+  const entry: AgentEntry = {
+    agent,
+    lastUsed: Date.now(),
+    timer: setTimeout(() => {
+      agent.destroy();
+      agentCache.delete(key);
+    }, AIRPLAY_AGENT_IDLE_MS),
+  };
+  if (typeof entry.timer.unref === 'function') entry.timer.unref();
+  agentCache.set(key, entry);
+  return agent;
+}
+
+/**
+ * Start AirPlay pairing: triggers PIN display on the Apple TV.
+ * Returns a session object to pass to finishAirPlayPairing.
+ */
+export async function startAirPlayPairing(host: string, port: number): Promise<AirPlayPairingSession> {
+  const srp = new SRPAuthHandler();
+  srp.initialize();
+  const agent = getPairingAgent(host, port);
+
+  // Trigger PIN display
+  await httpPost(host, port, '/pair-pin-start', undefined, agent);
+
+  // Send pair-setup SeqNo 1
+  const tlvData = writeTlv(new Map<number, Buffer>([
+    [TlvValue.Method, Buffer.from([0x00])],
+    [TlvValue.SeqNo, Buffer.from([0x01])],
+  ]));
+
+  const resp = await httpPost(host, port, '/pair-setup', tlvData, agent);
+  const pairingData = readTlv(resp);
+
+  const atvSalt = pairingData.get(TlvValue.Salt);
+  const atvPubKey = pairingData.get(TlvValue.PublicKey);
+
+  if (!atvSalt || !atvPubKey) {
+    throw new Error('Missing salt or public key in pair-setup response');
+  }
+
+  return { srp, host, port, atvSalt, atvPubKey };
+}
+
+/**
+ * Finish AirPlay pairing with the PIN shown on screen.
+ * Returns credentials for later connection.
+ */
+export async function finishAirPlayPairing(
+  session: AirPlayPairingSession,
+  pin: string,
+  displayName?: string,
+): Promise<HapCredentials> {
+  const { srp, host, port, atvSalt, atvPubKey } = session;
+  const agent = getPairingAgent(host, port);
+
+  console.log('[DEBUG] ATV Salt:', atvSalt.toString('hex'));
+  console.log('[DEBUG] ATV PubKey length:', atvPubKey.length);
+  console.log('[DEBUG] PIN:', pin);
+
+  // SRP step 1: set PIN
+  srp.step1(pin.trim());
+
+  // SRP step 2: compute proof
+  const [pubKey, proof] = srp.step2(atvPubKey, atvSalt);
+  console.log('[DEBUG] Client PubKey length:', pubKey.length);
+  console.log('[DEBUG] Client Proof length:', proof.length);
+
+  // Send pair-setup SeqNo 3
+  const seq3Data = writeTlv(new Map<number, Buffer>([
+    [TlvValue.SeqNo, Buffer.from([0x03])],
+    [TlvValue.PublicKey, pubKey],
+    [TlvValue.Proof, proof],
+  ]));
+  const seq3Resp = await httpPost(host, port, '/pair-setup', seq3Data, agent);
+
+  // Check for errors in SeqNo 3 response (wrong PIN, etc.)
+  const seq3Tlv = readTlv(seq3Resp);
+  console.log('[DEBUG] SeqNo 3 response TLV keys:', Array.from(seq3Tlv.keys()));
+  const errorCode = seq3Tlv.get(TlvValue.Error);
+  if (errorCode) {
+    const code = errorCode[0];
+    const errorMessages: Record<number, string> = {
+      1: 'Unknown error',
+      2: 'Authentication failed (wrong PIN?)',
+      3: 'Too many attempts, backoff required',
+      4: 'Unknown peer',
+      5: 'Max peers reached',
+      6: 'Max authentication attempts reached',
+    };
+    console.log('[DEBUG] Error code:', code);
+    console.log('[DEBUG] Full response hex:', seq3Resp.toString('hex'));
+    throw new Error(`Pairing failed: ${errorMessages[code] || `error code ${code}`}`);
+  }
+
+  // SRP step 3: sign and encrypt identity
+  const encrypted = srp.step3(displayName || undefined);
+
+  // Send pair-setup SeqNo 5
+  const seq5Data = writeTlv(new Map<number, Buffer>([
+    [TlvValue.SeqNo, Buffer.from([0x05])],
+    [TlvValue.EncryptedData, encrypted],
+  ]));
+  const resp = await httpPost(host, port, '/pair-setup', seq5Data, agent);
+  const pairingData = readTlv(resp);
+
+  const encryptedResponse = pairingData.get(TlvValue.EncryptedData);
+  if (!encryptedResponse) {
+    throw new Error('Missing encrypted data in pair-setup step 4 response');
+  }
+
+  // SRP step 4: decrypt and extract credentials
+  return srp.step4(encryptedResponse);
+}

package/src/bplist.ts

@@ -0,0 +1,136 @@
+/**
+ * Minimal binary plist support for RTI (Remote Text Input) NSKeyedArchiver payloads.
+ * Uses bplist-creator for encoding and bplist-parser for decoding.
+ */
+
+// @ts-ignore - no type definitions
+import bplistCreator from 'bplist-creator';
+// @ts-ignore - no type definitions
+import bplistParser from 'bplist-parser';
+
+/** UID reference type for NSKeyedArchiver plists. */
+class UID {
+  UID: number;
+  constructor(value: number) {
+    this.UID = value;
+  }
+}
+
+/**
+ * Create an RTI "clear text" payload (NSKeyedArchiver encoded).
+ * Matches pyatv/protocols/companion/plist_payloads/rti_text_operations.py
+ */
+export function createRtiClearTextPayload(sessionUuid: Buffer): Buffer {
+  return bplistCreator({
+    '$version': 100000,
+    '$archiver': 'RTIKeyedArchiver',
+    '$top': {
+      textOperations: new UID(1),
+    },
+    '$objects': [
+      '$null',
+      {
+        '$class': new UID(7),
+        targetSessionUUID: new UID(5),
+        keyboardOutput: new UID(2),
+        textToAssert: new UID(4),
+      },
+      {
+        '$class': new UID(3),
+      },
+      {
+        '$classname': 'TIKeyboardOutput',
+        '$classes': ['TIKeyboardOutput', 'NSObject'],
+      },
+      '',  // empty text assertion = clear
+      {
+        'NS.uuidbytes': sessionUuid,
+        '$class': new UID(6),
+      },
+      {
+        '$classname': 'NSUUID',
+        '$classes': ['NSUUID', 'NSObject'],
+      },
+      {
+        '$classname': 'RTITextOperations',
+        '$classes': ['RTITextOperations', 'NSObject'],
+      },
+    ],
+  });
+}
+
+/**
+ * Create an RTI "input text" payload (NSKeyedArchiver encoded).
+ */
+export function createRtiInputTextPayload(sessionUuid: Buffer, text: string): Buffer {
+  return bplistCreator({
+    '$version': 100000,
+    '$archiver': 'RTIKeyedArchiver',
+    '$top': {
+      textOperations: new UID(1),
+    },
+    '$objects': [
+      '$null',
+      {
+        keyboardOutput: new UID(2),
+        '$class': new UID(7),
+        targetSessionUUID: new UID(5),
+      },
+      {
+        insertionText: new UID(3),
+        '$class': new UID(4),
+      },
+      text,
+      {
+        '$classname': 'TIKeyboardOutput',
+        '$classes': ['TIKeyboardOutput', 'NSObject'],
+      },
+      {
+        'NS.uuidbytes': sessionUuid,
+        '$class': new UID(6),
+      },
+      {
+        '$classname': 'NSUUID',
+        '$classes': ['NSUUID', 'NSObject'],
+      },
+      {
+        '$classname': 'RTITextOperations',
+        '$classes': ['RTITextOperations', 'NSObject'],
+      },
+    ],
+  });
+}
+
+/**
+ * Parse a binary plist buffer and extract properties by path.
+ * Matches pyatv/protocols/companion/keyed_archiver.py read_archive_properties().
+ */
+export function readArchiveProperties(archive: Buffer, ...paths: string[][]): (unknown | null)[] {
+  let parsed: any[];
+  try {
+    parsed = bplistParser.parseBuffer(archive);
+  } catch {
+    return paths.map(() => null);
+  }
+  if (!parsed || !Array.isArray(parsed) || parsed.length < 1) return paths.map(() => null);
+
+  const data = parsed[0];
+  const objects = data['$objects'];
+  const top = data['$top'];
+
+  return paths.map((path) => {
+    let element: any = top;
+    try {
+      for (const key of path) {
+        element = element[key];
+        // Resolve UID references
+        if (element && typeof element === 'object' && 'UID' in element) {
+          element = objects[element.UID];
+        }
+      }
+      return element ?? null;
+    } catch {
+      return null;
+    }
+  });
+}

package/src/companion/auth.ts

@@ -0,0 +1,141 @@
+/**
+ * Companion protocol pair-setup and pair-verify procedures.
+ * Port of pyatv/protocols/companion/auth.py.
+ */
+
+import { SRPAuthHandler } from '../pairing/srp';
+import { HapCredentials } from '../pairing/credentials';
+import { TlvValue, readTlv, writeTlv } from '../pairing/tlv';
+import { CompanionProtocol } from './protocol';
+import { FrameType } from './connection';
+
+const PAIRING_DATA_KEY = '_pd';
+
+// Companion encryption key derivation constants
+export const SRP_SALT = '';
+export const SRP_OUTPUT_INFO = 'ClientEncrypt-main';
+export const SRP_INPUT_INFO = 'ServerEncrypt-main';
+
+function getPairingData(message: Record<string, unknown>): Map<number, Buffer> {
+  const pd = message[PAIRING_DATA_KEY];
+  if (!pd || !Buffer.isBuffer(pd)) {
+    throw new Error('No pairing data in message or unexpected type');
+  }
+  const tlv = readTlv(pd);
+  if (tlv.has(TlvValue.Error)) {
+    throw new Error(`Pairing error: ${tlv.get(TlvValue.Error)!.toString('hex')}`);
+  }
+  return tlv;
+}
+
+/**
+ * Perform Companion pair-setup (initial pairing that requires PIN).
+ */
+export class CompanionPairSetupProcedure {
+  private protocol: CompanionProtocol;
+  private srp: SRPAuthHandler;
+  private atvSalt: Buffer | null = null;
+  private atvPubKey: Buffer | null = null;
+
+  constructor(protocol: CompanionProtocol, srp: SRPAuthHandler) {
+    this.protocol = protocol;
+    this.srp = srp;
+  }
+
+  async startPairing(): Promise<void> {
+    this.srp.initialize();
+    await this.protocol.start();
+
+    const resp = await this.protocol.exchangeAuth(FrameType.PS_Start, {
+      [PAIRING_DATA_KEY]: writeTlv(new Map<number, Buffer>([
+        [TlvValue.Method, Buffer.from([0x00])],
+        [TlvValue.SeqNo, Buffer.from([0x01])],
+      ])),
+      _pwTy: 1,
+    });
+
+    const pairingData = getPairingData(resp);
+    this.atvSalt = pairingData.get(TlvValue.Salt)!;
+    this.atvPubKey = pairingData.get(TlvValue.PublicKey)!;
+  }
+
+  async finishPairing(pin: string, displayName?: string): Promise<HapCredentials> {
+    this.srp.step1(pin);
+
+    const [pubKey, proof] = this.srp.step2(this.atvPubKey!, this.atvSalt!);
+
+    // SeqNo 3: send proof
+    const resp3 = await this.protocol.exchangeAuth(FrameType.PS_Next, {
+      [PAIRING_DATA_KEY]: writeTlv(new Map<number, Buffer>([
+        [TlvValue.SeqNo, Buffer.from([0x03])],
+        [TlvValue.PublicKey, pubKey],
+        [TlvValue.Proof, proof],
+      ])),
+      _pwTy: 1,
+    });
+
+    // Verify server proof is present
+    getPairingData(resp3);
+
+    // SeqNo 5: send encrypted identity
+    const encrypted = this.srp.step3(displayName);
+    const resp5 = await this.protocol.exchangeAuth(FrameType.PS_Next, {
+      [PAIRING_DATA_KEY]: writeTlv(new Map<number, Buffer>([
+        [TlvValue.SeqNo, Buffer.from([0x05])],
+        [TlvValue.EncryptedData, encrypted],
+      ])),
+      _pwTy: 1,
+    });
+
+    const pairingData5 = getPairingData(resp5);
+    const encryptedData = pairingData5.get(TlvValue.EncryptedData)!;
+
+    return this.srp.step4(encryptedData);
+  }
+}
+
+/**
+ * Verify Companion credentials and derive encryption keys.
+ */
+export class CompanionPairVerifyProcedure {
+  private protocol: CompanionProtocol;
+  private srp: SRPAuthHandler;
+  private credentials: HapCredentials;
+
+  constructor(protocol: CompanionProtocol, srp: SRPAuthHandler, credentials: HapCredentials) {
+    this.protocol = protocol;
+    this.srp = srp;
+    this.credentials = credentials;
+  }
+
+  async verifyCredentials(): Promise<boolean> {
+    const [, publicKey] = this.srp.initialize();
+
+    const resp = await this.protocol.exchangeAuth(FrameType.PV_Start, {
+      [PAIRING_DATA_KEY]: writeTlv(new Map<number, Buffer>([
+        [TlvValue.SeqNo, Buffer.from([0x01])],
+        [TlvValue.PublicKey, publicKey],
+      ])),
+      _auTy: 4,
+    });
+
+    const pairingData = getPairingData(resp);
+    const serverPubKey = pairingData.get(TlvValue.PublicKey)!;
+    const encrypted = pairingData.get(TlvValue.EncryptedData)!;
+
+    const encryptedData = this.srp.verify1(this.credentials, serverPubKey, encrypted);
+
+    await this.protocol.exchangeAuth(FrameType.PV_Next, {
+      [PAIRING_DATA_KEY]: writeTlv(new Map<number, Buffer>([
+        [TlvValue.SeqNo, Buffer.from([0x03])],
+        [TlvValue.EncryptedData, encryptedData],
+      ])),
+    });
+
+    return true;
+  }
+
+  encryptionKeys(): [Buffer, Buffer] {
+    return this.srp.verify2(SRP_SALT, SRP_OUTPUT_INFO, SRP_INPUT_INFO);
+  }
+}

package/src/companion/connection.ts

@@ -0,0 +1,161 @@
+/**
+ * Companion protocol TCP connection with frame-based protocol.
+ * Port of pyatv/protocols/companion/connection.py.
+ *
+ * Frame format: [1-byte FrameType][3-byte big-endian payload length][payload]
+ * When encrypted, payload includes 16-byte auth tag in the length field.
+ */
+
+import * as net from 'net';
+import { EventEmitter } from 'events';
+import { Chacha20Cipher, AUTH_TAG_LENGTH } from '../crypto/chacha20';
+import * as opack from '../opack';
+
+export enum FrameType {
+  Unknown = 0,
+  NoOp = 1,
+  PS_Start = 3,
+  PS_Next = 4,
+  PV_Start = 5,
+  PV_Next = 6,
+  U_OPACK = 7,
+  E_OPACK = 8,
+  P_OPACK = 9,
+  PA_Req = 10,
+  PA_Rsp = 11,
+  SessionStartRequest = 16,
+  SessionStartResponse = 17,
+  SessionData = 18,
+  FamilyIdentityRequest = 32,
+  FamilyIdentityResponse = 33,
+  FamilyIdentityUpdate = 34,
+}
+
+const HEADER_LENGTH = 4;
+
+export interface FrameListener {
+  frameReceived(frameType: FrameType, payload: Buffer): void;
+  connectionLost(error?: Error): void;
+}
+
+export class CompanionConnection {
+  private socket: net.Socket | null = null;
+  private buffer = Buffer.alloc(0);
+  private chacha: Chacha20Cipher | null = null;
+  private listener: FrameListener;
+  private host: string;
+  private port: number;
+  private connected = false;
+
+  constructor(host: string, port: number, listener?: FrameListener) {
+    this.host = host;
+    this.port = port;
+    this.listener = listener || { frameReceived: () => {}, connectionLost: () => {} };
+  }
+
+  setListener(listener: FrameListener): void {
+    this.listener = listener;
+  }
+
+  async connect(): Promise<void> {
+    if (this.connected) return;
+    return new Promise((resolve, reject) => {
+      this.socket = net.createConnection({ host: this.host, port: this.port }, () => {
+        this.connected = true;
+        if (this.socket && typeof this.socket.unref === 'function') this.socket.unref();
+        resolve();
+      });
+
+      this.socket.on('data', (data: Buffer) => {
+        this.buffer = Buffer.concat([this.buffer, data]);
+        this.processBuffer();
+      });
+
+      this.socket.on('error', (err) => {
+        if (!this.connected) {
+          reject(err);
+        } else {
+          this.listener.connectionLost(err);
+        }
+      });
+
+      this.socket.on('close', () => {
+        this.connected = false;
+        this.listener.connectionLost();
+      });
+    });
+  }
+
+  private processBuffer(): void {
+    while (this.buffer.length >= HEADER_LENGTH) {
+      const payloadLength = HEADER_LENGTH + (
+        (this.buffer[1] << 16) | (this.buffer[2] << 8) | this.buffer[3]
+      );
+
+      if (this.buffer.length < payloadLength) break;
+
+      const header = this.buffer.subarray(0, HEADER_LENGTH);
+      let payload: Buffer = Buffer.from(this.buffer.subarray(HEADER_LENGTH, payloadLength)) as Buffer;
+      this.buffer = this.buffer.subarray(payloadLength);
+
+      if (this.chacha && payload.length > 0) {
+        try {
+          payload = this.chacha.decrypt(payload, undefined, header);
+        } catch (err) {
+          // Decryption failed, skip this frame
+          continue;
+        }
+      }
+
+      this.listener.frameReceived(header[0] as FrameType, payload);
+    }
+  }
+
+  send(frameType: FrameType, data: Buffer): void {
+    if (!this.socket || !this.connected) {
+      throw new Error('Not connected');
+    }
+
+    let payloadLength = data.length;
+    if (this.chacha && payloadLength > 0) {
+      payloadLength += AUTH_TAG_LENGTH;
+    }
+
+    const header = Buffer.alloc(HEADER_LENGTH);
+    header[0] = frameType;
+    header[1] = (payloadLength >> 16) & 0xff;
+    header[2] = (payloadLength >> 8) & 0xff;
+    header[3] = payloadLength & 0xff;
+
+    let payload = data;
+    if (this.chacha && data.length > 0) {
+      payload = this.chacha.encrypt(data, undefined, header);
+    }
+
+    this.socket.write(Buffer.concat([header, payload]));
+  }
+
+  enableEncryption(outputKey: Buffer, inputKey: Buffer): void {
+    this.chacha = new Chacha20Cipher(outputKey, inputKey, 12);
+  }
+
+  close(): void {
+    this.connected = false;
+    if (this.socket) {
+      this.socket.destroy();
+      this.socket = null;
+    }
+  }
+
+  get isConnected(): boolean {
+    return this.connected;
+  }
+
+  getHost(): string {
+    return this.host;
+  }
+
+  getPort(): number {
+    return this.port;
+  }
+}