ai-remote 0.1.0

package/src/protocols/rdp/rail.ts

@@ -0,0 +1,480 @@
+// Remote Applications Integrated Locally (RAIL), MS-RDPERP.
+//
+// This module owns the RAIL static virtual-channel messages. Window pixels
+// still use the ordinary RDP graphics path; RAIL supplies the session mode,
+// application launch request, and window lifecycle metadata around them.
+
+import { Reader, Writer } from './buffer';
+
+export const RAIL_ORDER = {
+  EXEC: 0x0001,
+  ACTIVATE: 0x0002,
+  SYSPARAM: 0x0003,
+  SYSCOMMAND: 0x0004,
+  HANDSHAKE: 0x0005,
+  WINDOW_MOVE: 0x0008,
+  CLIENT_STATUS: 0x000b,
+  EXEC_RESULT: 0x0080,
+  HANDSHAKE_EX: 0x0013,
+};
+
+export const RAIL_EXEC_RESULT = {
+  0x0000: 'The remote application started.',
+  0x0001: 'The RemoteApp host could not load its application monitoring hook.',
+  0x0002: 'The RemoteApp host could not decode the application launch request.',
+  0x0003: 'The requested application is not in the host RemoteApp allowlist.',
+  0x0005: 'The requested remote application was not found.',
+  0x0006: 'The RemoteApp host could not start the requested application.',
+  0x0007: 'The RemoteApp session is locked and cannot start the application.',
+};
+
+/** WM_SYSCOMMAND values a RAIL client may ask the host to apply to a window. */
+export const SYS_COMMAND = {
+  MINIMIZE: 0xf020,
+  MAXIMIZE: 0xf030,
+  CLOSE: 0xf060,
+  RESTORE: 0xf120,
+};
+
+/** SW_* show states reported by a window order's ShowState field. */
+export const SHOW_STATE = {
+  HIDDEN: 0,
+  MINIMIZED: 2,
+  MAXIMIZED: 3,
+  NORMAL: 5,
+};
+
+export const WINDOW_ORDER = {
+  TYPE_WINDOW: 0x01000000,
+  STATE_NEW: 0x10000000,
+  STATE_DELETED: 0x20000000,
+  ICON: 0x40000000,
+  CACHED_ICON: 0x80000000,
+};
+
+/**
+ * Window Information Order fields (MS-RDPERP 2.2.1.3.1.2.1). A field is present
+ * only when its flag is set, and present fields arrive in the fixed order the
+ * parser below reads them in, so an unrecognised combination cannot be skipped
+ * field by field -- the order's own size is what re-syncs the stream.
+ */
+const WINDOW_FIELD = {
+  OWNER: 0x00000002,
+  TITLE: 0x00000004,
+  STYLE: 0x00000008,
+  SHOW: 0x00000010,
+  WND_RECTS: 0x00000100,
+  WND_SIZE: 0x00000400,
+  WND_OFFSET: 0x00000800,
+  CLIENT_AREA_OFFSET: 0x00004000,
+  CLIENT_DELTA: 0x00008000,
+  CLIENT_AREA_SIZE: 0x00010000,
+  RP_CONTENT: 0x00020000,
+  ROOT_PARENT: 0x00040000,
+  VISIBILITY: 0x00080000,
+  VIS_OFFSET: 0x00200000,
+};
+
+/** Window styles that mark a window as something other than the app's own. */
+const STYLE_CHILD = 0x40000000;
+const EX_STYLE_TOOLWINDOW = 0x00000080;
+const EX_STYLE_NOACTIVATE = 0x08000000;
+
+const DRAWING_ORDER_CLASS_MASK = 0x03;
+const DRAWING_ORDER_ALT_SECONDARY = 0x02;
+const ALTSEC_WINDOW = 0x0b;
+
+const CLIENT_BUILD = 2600;
+const CLIENT_STATUS_SUPPRESS_ICON_ORDERS = 0x00000400;
+
+const SYSTEM_PARAMETER = {
+  MOUSE_BUTTON_SWAP: 0x00000021,
+  DRAG_FULL_WINDOWS: 0x00000025,
+  WORK_AREA: 0x0000002f,
+  HIGH_CONTRAST: 0x00000043,
+  KEYBOARD_PREF: 0x00000045,
+  KEYBOARD_CUES: 0x0000100b,
+};
+
+function utf16Bytes(text: string) {
+  const writer = new Writer(text.length * 2);
+  writer.utf16le(text);
+  return writer.take();
+}
+
+function pdu(orderType, body: Uint8Array) {
+  const writer = new Writer(body.length + 4);
+  writer.u16le(orderType).u16le(body.length + 4).raw(body);
+  return writer.take();
+}
+
+/** Window coordinates are signed: an off-screen or bordered window is normal. */
+function signed32(value) {
+  return value | 0;
+}
+
+export function railHandshake(buildNumber = CLIENT_BUILD) {
+  return pdu(RAIL_ORDER.HANDSHAKE, new Writer(4).u32le(buildNumber).take());
+}
+
+export function railClientStatus(flags = CLIENT_STATUS_SUPPRESS_ICON_ORDERS) {
+  return pdu(RAIL_ORDER.CLIENT_STATUS, new Writer(4).u32le(flags).take());
+}
+
+function railBooleanSystemParameter(parameter, enabled: boolean) {
+  return pdu(RAIL_ORDER.SYSPARAM, new Writer(5).u32le(parameter).u8(enabled ? 1 : 0).take());
+}
+
+function railHighContrast() {
+  const body = new Writer(16);
+  body.u32le(SYSTEM_PARAMETER.HIGH_CONTRAST);
+  body.u32le(0x0000007e); // HCF_AVAILABLE through HCF_HOTKEYAVAILABLE
+  body.u32le(2);          // empty color scheme including its terminator
+  body.u16le(0).u16le(0); // UNICODE_STRING length and terminator
+  return pdu(RAIL_ORDER.SYSPARAM, body.take());
+}
+
+/**
+ * SPI_SETWORKAREA. This is how a RAIL client tells the host how much room it
+ * has, and the host maximizes remote windows into it. Sending it again during
+ * the session is what keeps a maximized window matched to the browser window.
+ */
+export function railWorkArea(width: number, height: number) {
+  const body = new Writer(12);
+  body.u32le(SYSTEM_PARAMETER.WORK_AREA);
+  body.u16le(0).u16le(0).u16le(width).u16le(height);
+  return pdu(RAIL_ORDER.SYSPARAM, body.take());
+}
+
+export function railSystemParameters(width: number, height: number) {
+  return [
+    railHighContrast(),
+    railBooleanSystemParameter(SYSTEM_PARAMETER.MOUSE_BUTTON_SWAP, false),
+    railBooleanSystemParameter(SYSTEM_PARAMETER.KEYBOARD_PREF, false),
+    railBooleanSystemParameter(SYSTEM_PARAMETER.DRAG_FULL_WINDOWS, true),
+    railBooleanSystemParameter(SYSTEM_PARAMETER.KEYBOARD_CUES, false),
+    railWorkArea(width, height),
+  ];
+}
+
+/** TS_RAIL_ORDER_ACTIVATE: give (or take) input focus for one remote window. */
+export function railActivate(windowId: number, enabled = true) {
+  const body = new Writer(5);
+  body.u32le(windowId).u8(enabled ? 1 : 0);
+  return pdu(RAIL_ORDER.ACTIVATE, body.take());
+}
+
+/** TS_RAIL_ORDER_SYSCOMMAND: minimize, maximize, restore or close a window. */
+export function railSysCommand(windowId: number, command: string) {
+  const body = new Writer(6);
+  body.u32le(windowId).u16le(command);
+  return pdu(RAIL_ORDER.SYSCOMMAND, body.take());
+}
+
+/**
+ * TS_RAIL_ORDER_WINDOWMOVE. A client that draws remote windows itself sends
+ * this when the user finishes moving or resizing one; the host then applies
+ * the rectangle to the real window. It is the only way to give a remote window
+ * an exact size, which is what fitting one to the browser viewport needs.
+ */
+export function railWindowMove(windowId: number, { left, top, right, bottom }) {
+  const body = new Writer(12);
+  body.u32le(windowId);
+  body.u16le(left & 0xffff).u16le(top & 0xffff);
+  body.u16le(right & 0xffff).u16le(bottom & 0xffff);
+  return pdu(RAIL_ORDER.WINDOW_MOVE, body.take());
+}
+
+/** Build TS_RAIL_ORDER_EXEC. Strings are UTF-16LE and are not terminated. */
+export function railExecute({ program, workingDir = '', arguments: args = '' }) {
+  const exe = utf16Bytes(program || '');
+  const cwd = utf16Bytes(workingDir || '');
+  const argv = utf16Bytes(args || '');
+
+  if (exe.length === 0 || exe.length > 520) {
+    throw new Error('RemoteApp program must be between 1 and 260 Unicode characters.');
+  }
+  if (cwd.length > 520) throw new Error('RemoteApp working directory is too long.');
+  if (argv.length > 16000) throw new Error('RemoteApp arguments are too long.');
+
+  const body = new Writer(8 + exe.length + cwd.length + argv.length);
+  body.u16le(0); // executable, with no environment expansion requested
+  body.u16le(exe.length).u16le(cwd.length).u16le(argv.length);
+  body.raw(exe).raw(cwd).raw(argv);
+  return pdu(RAIL_ORDER.EXEC, body.take());
+}
+
+function decodeUtf16(bytes: Uint8Array) {
+  let result = '';
+  for (let i = 0; i + 1 < bytes.length; i += 2) {
+    const codeUnit = bytes[i] | (bytes[i + 1] << 8);
+    if (codeUnit === 0) break;
+    result += String.fromCharCode(codeUnit);
+  }
+  return result;
+}
+
+function readRectangles(reader: Reader, count: number) {
+  const rectangles = [];
+  for (let index = 0; index < count && reader.remaining >= 8; index++) {
+    const left = reader.u16le();
+    const top = reader.u16le();
+    const right = reader.u16le();
+    const bottom = reader.u16le();
+    rectangles.push({ left, top, right, bottom });
+  }
+  return rectangles;
+}
+
+/**
+ * Read the present fields of one Window Information Order. Fields the client
+ * has no use for are still read, because every later field's position depends
+ * on them.
+ */
+function parseWindowFields(reader: Reader, fieldFlags) {
+  const fields = {};
+
+  if (fieldFlags & WINDOW_FIELD.OWNER) fields.ownerWindowId = reader.u32le();
+  if (fieldFlags & WINDOW_FIELD.STYLE) {
+    fields.style = reader.u32le();
+    fields.extendedStyle = reader.u32le();
+  }
+  if (fieldFlags & WINDOW_FIELD.SHOW) fields.showState = reader.u8();
+  if (fieldFlags & WINDOW_FIELD.TITLE) {
+    const titleBytes = reader.u16le();
+    fields.title = decodeUtf16(reader.raw(Math.min(titleBytes, reader.remaining)));
+  }
+  if (fieldFlags & WINDOW_FIELD.CLIENT_AREA_OFFSET) {
+    fields.clientOffsetX = signed32(reader.u32le());
+    fields.clientOffsetY = signed32(reader.u32le());
+  }
+  if (fieldFlags & WINDOW_FIELD.CLIENT_AREA_SIZE) {
+    fields.clientWidth = signed32(reader.u32le());
+    fields.clientHeight = signed32(reader.u32le());
+  }
+  if (fieldFlags & WINDOW_FIELD.RP_CONTENT) reader.u8();
+  if (fieldFlags & WINDOW_FIELD.ROOT_PARENT) reader.u32le();
+  if (fieldFlags & WINDOW_FIELD.WND_OFFSET) {
+    fields.x = signed32(reader.u32le());
+    fields.y = signed32(reader.u32le());
+  }
+  if (fieldFlags & WINDOW_FIELD.CLIENT_DELTA) {
+    reader.u32le();
+    reader.u32le();
+  }
+  if (fieldFlags & WINDOW_FIELD.WND_SIZE) {
+    fields.width = signed32(reader.u32le());
+    fields.height = signed32(reader.u32le());
+  }
+  if (fieldFlags & WINDOW_FIELD.WND_RECTS) {
+    fields.windowRects = readRectangles(reader, reader.u16le());
+  }
+  if (fieldFlags & WINDOW_FIELD.VIS_OFFSET) {
+    fields.visibleOffsetX = signed32(reader.u32le());
+    fields.visibleOffsetY = signed32(reader.u32le());
+  }
+  if (fieldFlags & WINDOW_FIELD.VISIBILITY) {
+    fields.visibilityRects = readRectangles(reader, reader.u16le());
+  }
+
+  return fields;
+}
+
+/**
+ * True for a window the session exists to show: not a child, not a tool
+ * window, and not one of the never-activated popups a Chromium or Electron
+ * application creates for menus, tooltips and drag images.
+ */
+export function isPrimaryWindow(candidate) {
+  if (!candidate) return false;
+  if (candidate.ownerWindowId) return false;
+  if ((candidate.style || 0) & STYLE_CHILD) return false;
+  if ((candidate.extendedStyle || 0) & (EX_STYLE_TOOLWINDOW | EX_STYLE_NOACTIVATE)) return false;
+  return true;
+}
+
+/**
+ * Parse the window lifecycle subset of TS_UPDATE_ORDERS_PDU_DATA.
+ *
+ * RemoteApp window orders are Alternate Secondary orders and, unlike ordinary
+ * drawing orders, carry their total size in every header. That lets the parser
+ * read the fields it understands and then seek to the next order, rather than
+ * having to understand every icon, notification and desktop order to stay in
+ * sync with the stream.
+ */
+export function parseRemoteAppWindowOrders(reader: Reader) {
+  if (reader.remaining < 6) throw new Error('RDP RemoteApp orders update is truncated.');
+
+  reader.u16le(); // pad2OctetsA
+  const numberOrders = reader.u16le();
+  reader.u16le(); // pad2OctetsB
+  const events = [];
+
+  for (let index = 0; index < numberOrders && reader.remaining > 0; index++) {
+    const orderStart = reader.offset;
+    const controlFlags = reader.u8();
+    const orderClass = controlFlags & DRAWING_ORDER_CLASS_MASK;
+    const orderType = controlFlags >> 2;
+
+    // No primary drawing orders are advertised. If a broken host mixes one in,
+    // stop rather than guessing its variable-length encoding and losing sync.
+    if (orderClass !== DRAWING_ORDER_ALT_SECONDARY || orderType !== ALTSEC_WINDOW) break;
+    if (reader.remaining < 6) throw new Error('RDP RemoteApp window-order header is truncated.');
+
+    const orderSize = reader.u16le();
+    const fieldFlags = reader.u32le();
+    const orderEnd = orderStart + orderSize;
+    if (orderSize < 7 || orderEnd > reader.bytes.length) {
+      throw new Error('RDP RemoteApp window order has an invalid size.');
+    }
+
+    const describesWindow = Boolean(fieldFlags & WINDOW_ORDER.TYPE_WINDOW);
+    const isIconOrder = Boolean(fieldFlags & (WINDOW_ORDER.ICON | WINDOW_ORDER.CACHED_ICON));
+
+    if (describesWindow && !isIconOrder && orderEnd - reader.offset >= 4) {
+      const windowId = reader.u32le();
+      // A malformed order must not take the session down: the next update
+      // repeats the window state anyway, and the seek below keeps the stream
+      // aligned either way.
+      let fields = {};
+      try {
+        fields = parseWindowFields(reader, fieldFlags);
+      } catch (error) {
+        console.warn('[RDP] Dropped an unreadable RemoteApp window order', {
+          windowId,
+          fieldFlags: `0x${(fieldFlags >>> 0).toString(16)}`,
+          error: error instanceof Error ? error.message : String(error),
+        });
+      }
+
+      let type = 'update';
+      if (fieldFlags & WINDOW_ORDER.STATE_DELETED) type = 'deleted';
+      else if (fieldFlags & WINDOW_ORDER.STATE_NEW) type = 'new';
+      events.push({ type, windowId, fieldFlags, ...fields });
+    }
+
+    // The order's own size is authoritative, so an order carrying fields this
+    // parser skipped still leaves the reader on the next order's first byte.
+    reader.offset = orderEnd;
+    if (reader.offset <= orderStart) break;
+  }
+
+  return events;
+}
+
+/** Parse one or more complete RAIL PDUs delivered in a channel message. */
+export function parseRailPdus(bytes: Uint8Array) {
+  const reader = new Reader(bytes);
+  const messages = [];
+
+  while (reader.remaining >= 4) {
+    const orderType = reader.u16le();
+    const orderLength = reader.u16le();
+    if (orderLength < 4 || orderLength - 4 > reader.remaining) {
+      throw new Error('RDP RemoteApp channel delivered a malformed PDU.');
+    }
+
+    const body = new Reader(reader.raw(orderLength - 4));
+    if (orderType === RAIL_ORDER.HANDSHAKE && body.remaining >= 4) {
+      messages.push({ type: 'handshake', buildNumber: body.u32le() });
+      continue;
+    }
+    if (orderType === RAIL_ORDER.HANDSHAKE_EX && body.remaining >= 8) {
+      messages.push({ type: 'handshake', buildNumber: body.u32le(), flags: body.u32le(), extended: true });
+      continue;
+    }
+    if (orderType === RAIL_ORDER.EXEC_RESULT && body.remaining >= 12) {
+      const flags = body.u16le();
+      const result = body.u16le();
+      const rawResult = body.u32le();
+      body.u16le(); // padding
+      const nameLength = body.u16le();
+      const program = decodeUtf16(body.raw(Math.min(nameLength, body.remaining)));
+      messages.push({ type: 'execute-result', flags, result, rawResult, program });
+      continue;
+    }
+
+    messages.push({ type: 'unknown', orderType, body: body.rest().slice() });
+  }
+
+  return messages;
+}
+
+/**
+ * Minimal RAIL endpoint for the browser client. It deliberately suppresses
+ * icon orders because the browser currently presents the RemoteApp session in
+ * one canvas rather than creating a local OS window per remote window.
+ */
+export class RailChannel {
+  private readonly application: RemoteAppLaunch;
+  private width: number;
+  private height: number;
+  private readonly send: (bytes: Uint8Array) => void;
+  private readonly onReady: () => void;
+  private readonly onResult: (result: RailResult) => void;
+  private started: boolean;
+
+  constructor({ application, width, height, send, onReady, onResult }) {
+    this.application = application;
+    this.width = width;
+    this.height = height;
+    this.send = send;
+    this.onReady = onReady;
+    this.onResult = onResult;
+    this.started = false;
+  }
+
+  receive(bytes: Uint8Array) {
+    for (const message of parseRailPdus(bytes)) {
+      if (message.type === 'handshake') {
+        if (this.started) continue;
+        this.started = true;
+        this.send(railHandshake(CLIENT_BUILD));
+        this.send(railClientStatus());
+        for (const systemParameter of railSystemParameters(this.width, this.height)) {
+          this.send(systemParameter);
+        }
+        this.send(railExecute(this.application));
+        this.onReady?.(message);
+        continue;
+      }
+
+      if (message.type === 'execute-result') {
+        this.onResult?.({
+          ...message,
+          ok: message.result === 0,
+          message: RAIL_EXEC_RESULT[message.result] ||
+            `The RemoteApp host returned launch result 0x${message.result.toString(16).padStart(4, '0')}.`,
+        });
+      }
+    }
+  }
+
+  /** Republish the client's work area, which is what maximize resizes into. */
+  setWorkArea(width: number, height: number) {
+    if (!this.started || width <= 0 || height <= 0) return false;
+    if (width === this.width && height === this.height) return false;
+    this.width = width;
+    this.height = height;
+    this.send(railWorkArea(width, height));
+    return true;
+  }
+
+  activate(windowId: number) {
+    if (!this.started) return false;
+    this.send(railActivate(windowId, true));
+    return true;
+  }
+
+  sysCommand(windowId: number, command: string) {
+    if (!this.started) return false;
+    this.send(railSysCommand(windowId, command));
+    return true;
+  }
+
+  moveWindow(windowId: number, rectangle) {
+    if (!this.started) return false;
+    this.send(railWindowMove(windowId, rectangle));
+    return true;
+  }
+}